github-mirror/Telegram-iOS
1
0
Fork 0
mirror of https://github.com/TelegramMessenger/Telegram-iOS.git synced 2026-07-05 19:28:46 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'master' of gitlab.com:peter-iakovlev/telegram-ios

Browse source 
# Conflicts:
#	submodules/MetalEngine/Sources/MetalEngine.swift
This commit is contained in:
Mikhail Filimonov 2026-05-02 10:10:18 +01:00
commit 5b56675b06
257 changed files with 5559 additions and 22070 deletions
Download patch file Download diff file Expand all files Collapse all files

40
.bazelrc
View file

@ -1,32 +1,34 @@
build --action_env=ZERO_AR_DATE=1
build --apple_platform_type=ios
build --enable_platform_specific_config
build --apple_crosstool_top=@local_config_apple_cc//:toolchain
build --crosstool_top=@local_config_apple_cc//:toolchain
build --host_crosstool_top=@local_config_apple_cc//:toolchain
build --per_file_copt=".*\.m$","@-fno-objc-msgsend-selector-stubs"
build --per_file_copt=".*\.mm$","@-fno-objc-msgsend-selector-stubs"
build --features=debug_prefix_map_pwd_is_dot
build --features=swift.cacheable_swiftmodules
build --features=swift.debug_prefix_map
build --features=swift.enable_vfsoverlays
# macOS-specific settings (auto-applied on macOS via --enable_platform_specific_config)
build:macos --apple_platform_type=ios
build:macos --apple_crosstool_top=@local_config_apple_cc//:toolchain
build:macos --crosstool_top=@local_config_apple_cc//:toolchain
build:macos --host_crosstool_top=@local_config_apple_cc//:toolchain
build:macos --per_file_copt=".*\.m$","@-fno-objc-msgsend-selector-stubs"
build:macos --per_file_copt=".*\.mm$","@-fno-objc-msgsend-selector-stubs"
build:macos --features=debug_prefix_map_pwd_is_dot
build:macos --features=swift.cacheable_swiftmodules
build:macos --features=swift.debug_prefix_map
build:macos --features=swift.enable_vfsoverlays
build:dbg --features=swift.emit_swiftsourceinfo
# Linux-specific settings (auto-applied on Linux via --enable_platform_specific_config)
build:linux --action_env=CC
build:linux --action_env=CXX
build --strategy=Genrule=standalone
build --spawn_strategy=standalone
build --strategy=SwiftCompile=worker
build:macos --strategy=SwiftCompile=worker
#common --registry=https://raw.githubusercontent.com/bazelbuild/bazel-central-registry/main/
# SourceKit BSP: Swift indexing features
common --features=swift.index_while_building
common --features=swift.use_global_index_store
common --features=swift.use_global_module_cache
common --features=oso_prefix_is_pwd
# SourceKit BSP: Swift indexing features (macOS only)
common:macos --features=swift.index_while_building
common:macos --features=swift.use_global_index_store
common:macos --features=swift.use_global_module_cache
common:macos --features=oso_prefix_is_pwd
# SourceKit BSP: Index build config (used for background indexing)
common:index_build --experimental_convenience_symlinks=ignore

13
CLAUDE.md
View file

@ -147,3 +147,16 @@ All mediaBox methods with clean signatures (no Postbox-protocol leaks, no comple
**Facade-shape convention:** all of these take `EngineMediaResource.Id` or `EngineMediaResource` (never raw `MediaResourceId`/`MediaResource`). Return types either don't leak Postbox (`Void`, `String`, `String?`, `Signal<RangeSet<Int64>, NoError>`, `Signal<Float, NoError>`) or wrap via TelegramCore type (`Signal<EngineMediaResource.ResourceData, NoError>`).
**Swift-stdlib-vs-third-party-module name collisions** (learned in wave 26): `RangeSet<Int64>` collides with Swift stdlib's `RangeSet` (iOS 18+ only). Fix: `import RangeSet` at the file top of any TelegramCore file that names `RangeSet` in a signature. `TelegramCore/BUILD` already depends on `//submodules/Utils/RangeSet:RangeSet`. Future facade additions in TelegramEngineResources.swift should re-check this if new signature types are introduced.
## tgcalls Testbench
This repo includes a tgcalls testbench (CLI tool, Go/Pion SFU, Docker build) layered on top of the iOS source. All testbench code, build instructions, and architecture docs live inside the tgcalls submodule:
- `submodules/TgVoipWebrtc/tgcalls/CLAUDE.md` — top-level testbench overview, build/run commands
- `submodules/TgVoipWebrtc/tgcalls/tools/cli/CLAUDE.md` — CLI test tool architecture
- `submodules/TgVoipWebrtc/tgcalls/tools/go_sfu/CLAUDE.md` — Go SFU internals
- `submodules/TgVoipWebrtc/CLAUDE.md` — tgcalls library internals + macOS/Linux build patches
Build the test binary from this directory with:
`./build-input/bazel-8.4.2 build //submodules/TgVoipWebrtc/tgcalls/tools/cli:tgcalls_cli`

27
MODULE.bazel
View file

@ -3,6 +3,25 @@ http_file = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_
bazel_dep(name = "bazel_features", version = "1.33.0")
bazel_dep(name = "bazel_skylib", version = "1.8.1")
bazel_dep(name = "platforms", version = "0.0.11")
bazel_dep(name = "rules_go", version = "0.60.0", repo_name = "io_bazel_rules_go")
go_sdk = use_extension("@io_bazel_rules_go//go:extensions.bzl", "go_sdk")
go_sdk.download(version = "1.24.2")
bazel_dep(name = "gazelle", version = "0.43.0", repo_name = "bazel_gazelle")
go_deps = use_extension("@bazel_gazelle//:extensions.bzl", "go_deps")
go_deps.from_file(go_mod = "//submodules/TgVoipWebrtc/tgcalls/tools/go_sfu:go.mod")
use_repo(
go_deps,
"com_github_pion_datachannel",
"com_github_pion_dtls_v3",
"com_github_pion_ice_v4",
"com_github_pion_logging",
"com_github_pion_rtcp",
"com_github_pion_sctp",
"com_github_pion_srtp_v3",
)
bazel_dep(name = "rules_xcodeproj")
local_path_override(
@ -30,26 +49,26 @@ local_path_override(
http_file(
name = "cmake_tar_gz",
urls = ["https://github.com/Kitware/CMake/releases/download/v4.1.2/cmake-4.1.2-macos-universal.tar.gz"],
sha256 = "3be85f5b999e327b1ac7d804cbc9acd767059e9f603c42ec2765f6ab68fbd367",
urls = ["https://github.com/Kitware/CMake/releases/download/v4.1.2/cmake-4.1.2-macos-universal.tar.gz"],
)
http_file(
name = "meson_tar_gz",
urls = ["https://github.com/mesonbuild/meson/releases/download/1.6.0/meson-1.6.0.tar.gz"],
sha256 = "999b65f21c03541cf11365489c1fad22e2418bb0c3d50ca61139f2eec09d5496",
urls = ["https://github.com/mesonbuild/meson/releases/download/1.6.0/meson-1.6.0.tar.gz"],
)
http_file(
name = "ninja-mac_zip",
urls = ["https://github.com/ninja-build/ninja/releases/download/v1.12.1/ninja-mac.zip"],
sha256 = "89a287444b5b3e98f88a945afa50ce937b8ffd1dcc59c555ad9b1baf855298c9",
urls = ["https://github.com/ninja-build/ninja/releases/download/v1.12.1/ninja-mac.zip"],
)
http_file(
name = "flatbuffers_zip",
urls = ["https://github.com/google/flatbuffers/archive/refs/tags/v24.12.23.zip"],
sha256 = "c5cd6a605ff20350c7faa19d8eeb599df6117ea4aabd16ac58a7eb5ba82df4e7",
urls = ["https://github.com/google/flatbuffers/archive/refs/tags/v24.12.23.zip"],
)
provisioning_profile_repository = use_extension("@build_bazel_rules_apple//apple:apple.bzl", "provisioning_profile_repository_extension")

17
MODULE.bazel.lock generated
View file

@ -13,6 +13,7 @@
"https://bcr.bazel.build/modules/abseil-cpp/20250127.1/MODULE.bazel": "c4a89e7ceb9bf1e25cf84a9f830ff6b817b72874088bf5141b314726e46a57c1",
"https://bcr.bazel.build/modules/abseil-cpp/20250512.1/MODULE.bazel": "d209fdb6f36ffaf61c509fcc81b19e81b411a999a934a032e10cd009a0226215",
"https://bcr.bazel.build/modules/abseil-cpp/20250512.1/source.json": "d725d73707d01bb46ab3ca59ba408b8e9bd336642ca77a2269d4bfb8bbfd413d",
"https://bcr.bazel.build/modules/bazel_features/1.1.0/MODULE.bazel": "cfd42ff3b815a5f39554d97182657f8c4b9719568eb7fded2b9135f084bf760b",
"https://bcr.bazel.build/modules/bazel_features/1.1.1/MODULE.bazel": "27b8c79ef57efe08efccbd9dd6ef70d61b4798320b8d3c134fd571f78963dbcd",
"https://bcr.bazel.build/modules/bazel_features/1.11.0/MODULE.bazel": "f9382337dd5a474c3b7d334c2f83e50b6eaedc284253334cf823044a26de03e8",
"https://bcr.bazel.build/modules/bazel_features/1.15.0/MODULE.bazel": "d38ff6e517149dc509406aca0db3ad1efdd890a85e049585b7234d04238e2a4d",
@ -46,6 +47,12 @@
"https://bcr.bazel.build/modules/bazel_skylib/1.9.0/source.json": "7ad77c1e8c1b84222d9b3f3cae016a76639435744c19330b0b37c0a3c9da7dc0",
"https://bcr.bazel.build/modules/buildozer/7.1.2/MODULE.bazel": "2e8dd40ede9c454042645fd8d8d0cd1527966aa5c919de86661e62953cd73d84",
"https://bcr.bazel.build/modules/buildozer/7.1.2/source.json": "c9028a501d2db85793a6996205c8de120944f50a0d570438fcae0457a5f9d1f8",
"https://bcr.bazel.build/modules/gazelle/0.32.0/MODULE.bazel": "b499f58a5d0d3537f3cf5b76d8ada18242f64ec474d8391247438bf04f58c7b8",
"https://bcr.bazel.build/modules/gazelle/0.33.0/MODULE.bazel": "a13a0f279b462b784fb8dd52a4074526c4a2afe70e114c7d09066097a46b3350",
"https://bcr.bazel.build/modules/gazelle/0.34.0/MODULE.bazel": "abdd8ce4d70978933209db92e436deb3a8b737859e9354fb5fd11fb5c2004c8a",
"https://bcr.bazel.build/modules/gazelle/0.36.0/MODULE.bazel": "e375d5d6e9a6ca59b0cb38b0540bc9a05b6aa926d322f2de268ad267a2ee74c0",
"https://bcr.bazel.build/modules/gazelle/0.43.0/MODULE.bazel": "846e1fe396eefc0f9ddad2b33e9bd364dd993fc2f42a88e31590fe0b0eefa3f0",
"https://bcr.bazel.build/modules/gazelle/0.43.0/source.json": "021a77f6625906d9d176e2fa351175e842622a5d45989312f2ad4924aab72df6",
"https://bcr.bazel.build/modules/google_benchmark/1.8.2/MODULE.bazel": "a70cf1bba851000ba93b58ae2f6d76490a9feb74192e57ab8e8ff13c34ec50cb",
"https://bcr.bazel.build/modules/googletest/1.11.0/MODULE.bazel": "3a83f095183f66345ca86aa13c58b59f9f94a2f81999c093d4eeaa2d262d12f4",
"https://bcr.bazel.build/modules/googletest/1.14.0.bcr.1/MODULE.bazel": "22c31a561553727960057361aa33bf20fb2e98584bc4fec007906e27053f80c6",
@ -76,6 +83,8 @@
"https://bcr.bazel.build/modules/protobuf/29.0-rc3/MODULE.bazel": "33c2dfa286578573afc55a7acaea3cada4122b9631007c594bf0729f41c8de92",
"https://bcr.bazel.build/modules/protobuf/29.0/MODULE.bazel": "319dc8bf4c679ff87e71b1ccfb5a6e90a6dbc4693501d471f48662ac46d04e4e",
"https://bcr.bazel.build/modules/protobuf/3.19.0/MODULE.bazel": "6b5fbb433f760a99a22b18b6850ed5784ef0e9928a72668b66e4d7ccd47db9b0",
"https://bcr.bazel.build/modules/protobuf/3.19.2/MODULE.bazel": "532ffe5f2186b69fdde039efe6df13ba726ff338c6bc82275ad433013fa10573",
"https://bcr.bazel.build/modules/protobuf/3.19.6/MODULE.bazel": "9233edc5e1f2ee276a60de3eaa47ac4132302ef9643238f23128fea53ea12858",
"https://bcr.bazel.build/modules/protobuf/34.0.bcr.1/MODULE.bazel": "74e541b0ba877813da786a11707d4e394433c157841d5111a36be0d44b907931",
"https://bcr.bazel.build/modules/protobuf/34.0.bcr.1/source.json": "fc174b3d6215aa14197d1bd779f98bb72d9fd666ee5ec0d6bba6ae986baa4535",
"https://bcr.bazel.build/modules/pybind11_bazel/2.11.1/MODULE.bazel": "88af1c246226d87e65be78ed49ecd1e6f5e98648558c14ce99176da041dc378e",
@ -106,6 +115,12 @@
"https://bcr.bazel.build/modules/rules_cc/0.2.17/source.json": "3832f45d145354049137c0090df04629d9c2b5493dc5c2bf46f1834040133a07",
"https://bcr.bazel.build/modules/rules_foreign_cc/0.9.0/MODULE.bazel": "c9e8c682bf75b0e7c704166d79b599f93b72cfca5ad7477df596947891feeef6",
"https://bcr.bazel.build/modules/rules_fuzzing/0.5.2/MODULE.bazel": "40c97d1144356f52905566c55811f13b299453a14ac7769dfba2ac38192337a8",
"https://bcr.bazel.build/modules/rules_go/0.41.0/MODULE.bazel": "55861d8e8bb0e62cbd2896f60ff303f62ffcb0eddb74ecb0e5c0cbe36fc292c8",
"https://bcr.bazel.build/modules/rules_go/0.42.0/MODULE.bazel": "8cfa875b9aa8c6fce2b2e5925e73c1388173ea3c32a0db4d2b4804b453c14270",
"https://bcr.bazel.build/modules/rules_go/0.46.0/MODULE.bazel": "3477df8bdcc49e698b9d25f734c4f3a9f5931ff34ee48a2c662be168f5f2d3fd",
"https://bcr.bazel.build/modules/rules_go/0.50.1/MODULE.bazel": "b91a308dc5782bb0a8021ad4330c81fea5bda77f96b9e4c117b9b9c8f6665ee0",
"https://bcr.bazel.build/modules/rules_go/0.60.0/MODULE.bazel": "4a57ff2ffc2a3570e3c5646575c5a4b07287e91bcdac5d1f72383d51502b48cb",
"https://bcr.bazel.build/modules/rules_go/0.60.0/source.json": "1e21368c5e0c3013a110bd79a8fcff8ca46b5bcb2b561713a7273cbfcff7c464",
"https://bcr.bazel.build/modules/rules_java/4.0.0/MODULE.bazel": "5a78a7ae82cd1a33cef56dc578c7d2a46ed0dca12643ee45edbb8417899e6f74",
"https://bcr.bazel.build/modules/rules_java/5.3.5/MODULE.bazel": "a4ec4f2db570171e3e5eb753276ee4b389bae16b96207e9d3230895c99644b86",
"https://bcr.bazel.build/modules/rules_java/6.0.0/MODULE.bazel": "8a43b7df601a7ec1af61d79345c17b31ea1fedc6711fd4abfd013ea612978e39",
@ -142,6 +157,7 @@
"https://bcr.bazel.build/modules/rules_proto/4.0.0/MODULE.bazel": "a7a7b6ce9bee418c1a760b3d84f83a299ad6952f9903c67f19e4edd964894e06",
"https://bcr.bazel.build/modules/rules_proto/5.3.0-21.7/MODULE.bazel": "e8dff86b0971688790ae75528fe1813f71809b5afd57facb44dad9e8eca631b7",
"https://bcr.bazel.build/modules/rules_proto/6.0.0-rc1/MODULE.bazel": "1e5b502e2e1a9e825eef74476a5a1ee524a92297085015a052510b09a1a09483",
"https://bcr.bazel.build/modules/rules_proto/6.0.0/MODULE.bazel": "b531d7f09f58dce456cd61b4579ce8c86b38544da75184eadaf0a7cb7966453f",
"https://bcr.bazel.build/modules/rules_proto/6.0.2/MODULE.bazel": "ce916b775a62b90b61888052a416ccdda405212b6aaeb39522f7dc53431a5e73",
"https://bcr.bazel.build/modules/rules_proto/7.0.2/MODULE.bazel": "bf81793bd6d2ad89a37a40693e56c61b0ee30f7a7fdbaf3eabbf5f39de47dea2",
"https://bcr.bazel.build/modules/rules_proto/7.0.2/source.json": "1e5e7260ae32ef4f2b52fd1d0de8d03b606a44c91b694d2f1afb1d3b28a48ce1",
@ -171,6 +187,7 @@
"https://bcr.bazel.build/modules/swift_argument_parser/1.7.0/source.json": "b9b952cba0c748083b9b891e6ac46d347c92d37e8a92ead96d2a54b966bacd87",
"https://bcr.bazel.build/modules/upb/0.0.0-20220923-a547704/MODULE.bazel": "7298990c00040a0e2f121f6c32544bab27d4452f80d9ce51349b1a28f3005c43",
"https://bcr.bazel.build/modules/zlib/1.2.11/MODULE.bazel": "07b389abc85fdbca459b69e2ec656ae5622873af3f845e1c9d80fe179f3effa0",
"https://bcr.bazel.build/modules/zlib/1.2.12/MODULE.bazel": "3b1a8834ada2a883674be8cbd36ede1b6ec481477ada359cd2d3ddc562340b27",
"https://bcr.bazel.build/modules/zlib/1.3.1.bcr.5/MODULE.bazel": "eec517b5bbe5492629466e11dae908d043364302283de25581e3eb944326c4ca",
"https://bcr.bazel.build/modules/zlib/1.3.1.bcr.5/source.json": "22bc55c47af97246cfc093d0acf683a7869377de362b5d1c552c2c2e16b7a806",
"https://bcr.bazel.build/modules/zlib/1.3.1/MODULE.bazel": "751c9940dcfe869f5f7274e1295422a34623555916eb98c174c1e945594bf198"

1
Telegram/BroadcastUpload/BroadcastUploadExtension.swift
View file

@ -163,6 +163,7 @@ private final class EmbeddedBroadcastUploadImpl: BroadcastUploadImpl {
enableNoiseSuppression: false,
disableAudioInput: true,
enableSystemMute: false,
useReferenceImpl: false,
prioritizeVP8: false,
logPath: "",
onMutedSpeechActivityDetected: { _ in },

2
Telegram/NotificationService/Sources/NotificationService.swift
View file

@ -2958,7 +2958,7 @@ extension Customoji {
if let cg = (image as UIImage).cgImage { return cg }
var rendered: CGImage?
let work = { rendered = renderCGImage(image as! UIImage) }
let work = { rendered = renderCGImage(image) }
if Thread.isMainThread {
work()
} else {

94
Telegram/Telegram-iOS/en.lproj/Localizable.strings
View file

@ -2067,6 +2067,7 @@
"StickerPack.Share" = "Share";
"StickerPack.Send" = "Send Sticker";
"StickerPack.AddSticker" = "Add Sticker";
"StickerPack.RemoveStickerSet" = "Remove Sticker Set";
"StickerPack.RemoveStickerCount_1" = "Remove 1 Sticker";
"StickerPack.RemoveStickerCount_2" = "Remove 2 Stickers";
@ -2706,6 +2707,7 @@ Unused sets are archived when you add more.";
"Channel.AdminLog.AddMembers" = "Add Members";
"Channel.AdminLog.SendPolls" = "Send Polls";
"Channel.AdminLog.ManageTopics" = "Manage Topics";
"Channel.AdminLog.SendReactions" = "Send Reactions";
"Channel.AdminLog.CanChangeInfo" = "Change Info";
"Channel.AdminLog.CanSendMessages" = "Post Messages";
@ -16154,6 +16156,41 @@ Error: %8$@";
"TextProcessing.ResultBadge" = "Result";
"TextProcessing.Translate.LanguageStyle" = "%1$@ (%2$@)";
"TextProcessing.StyleTooltip" = "Select Style";
"TextProcessing.AlertCreatorDeleteStyle.Title" = "Delete Style";
"TextProcessing.AlertCreatorDeleteStyle.Text" = "Are you sure you want to delete this style? It will be removed for everyone who installed it.";
"TextProcessing.AlertDeleteStyle.Title" = "Delete Style";
"TextProcessing.AlertDeleteStyle.Text" = "Are you sure you want to delete this style?";
"TextProcessing.StyleMenu.Edit" = "Edit Style";
"TextProcessing.StyleMenu.Share" = "Share Style";
"TextProcessing.StyleMenu.Delete" = "Delete Style";
"TextProcessing.StyleMenu.ButtonClose" = "Close";
"TextProcessing.StyleMenu.ButtonAdd" = "Add Style";
"TextProcessing.StylePreview.ExampleHeader" = "EXAMPLE";
"TextProcessing.StylePreview.ExampleHeaderRefresh" = "ANOTHER EXAMPLE";
"TextProcessing.StylePreview.Subtitle" = "Add this style to instantly\nrewrite your messages.";
"TextProcessing.StylePreview.Before" = "Before";
"TextProcessing.StylePreview.After" = "After";
"TextProcessing.AlertTooManyStyles.Title" = "Too Many Styles";
"TextProcessing.AlertTooManyStyles.Text" = "Please delete some of your saved styles to create a new one.";
"TextProcessing.ToastStyleCreated.Title" = "%@ style created!";
"TextProcessing.ToastStyleCreated.Text" = "Press and hold a style to edit or share the link.";
"TextProcessing.StyleList.Add" = "Add Style";
"TextProcessing.StyleFooterAuthor" = "Style by [%@]()";
"TextProcessing.StyleFooterUserCount_1" = "Used by 1 person";
"TextProcessing.StyleFooterUserCount_any" = "Used by %d people";
"TextProcessing.StyleFooterCreatedByFormat" = "%1$@. %2$@";
"TextProcessing.StyleFooterCreatedBy" = "Created by [%@]()";
"TextProcessing.StyleFooterCreatedBySimpleFormat" = "%@.";
"TextProcessing.EditStyle.NamePlaceholder" = "Style Name (for example, \"Pirate\")";
"TextProcessing.EditStyle.TextPlaceholder" = "Instructions (for example, \"Write like a swashbuckling pirate. Use arr, ye, matey, and talk about treasure, the sea, and rum\")";
"TextProcessing.EditStyle.TitleCreate" = "New Style";
"TextProcessing.EditStyle.TitleEdit" = "Edit Style";
"TextProcessing.EditStyle.ActionCreate" = "Create";
"TextProcessing.EditStyle.ActionEdit" = "Save";
"TextProcessing.EditStyle.Delete" = "Delete Style";
"TextProcessing.EditStyle.AddLink" = "Add a link to my account";
"TextProcessing.ToastStyleAdded.Title" = "Style Added";
"TextProcessing.ToastStyleAdded.Text" = "Tap 'AI' → '%@' when typing your next long message.";
"Bot.AlertCanNotCreateBots" = "%@ can't manage other bots.";
@ -16175,6 +16212,7 @@ Error: %8$@";
"CreatePoll.OptionsNeededOne" = "Add at least one option";
"CreatePoll.QuizCorrectOptionNeeded" = "Select a correct option";
"CreatePoll.QuizCorrectOptionNeededMultiple" = "Select at least one correct option";
"CreatePoll.QuizCountryNeeded" = "Select at least one country";
"Stars.Intro.Transaction.Commission.Title" = "%@ commission";
@ -16191,7 +16229,7 @@ Error: %8$@";
"CreatePoll.AllowedCountries.Countries_1" = "%@ country";
"CreatePoll.AllowedCountries.Countries_any" = "%@ countries";
"Chat.Poll.Restriction.Subscribers" = "Only subscribers of **%@** can vote";
"Chat.Poll.Restriction.Subscribers" = "Only subscribers of **%@** can vote.";
"Chat.Poll.Restriction.Subscribers.TimeLimit" = "Only subscribers who joined more than **24 hours** ago can vote.";
"Chat.Poll.Restriction.Country" = "Only users from %@ can vote.";
"Chat.Poll.Restriction.SubscribersCountry" = "Only subscribers of **%@** from %@ can vote.";
@ -16214,5 +16252,57 @@ Error: %8$@";
"Chat.AdminAction.ToastReactionsDeletedTitleSingle" = "Reaction Deleted";
"Chat.AdminAction.ToastReactionsDeletedTextSingle" = "Reaction Deleted.";
"Chat.AdminAction.ToastReactionsDeletedTextMultiple" = "Messages Deleted.";
"Chat.AdminAction.ToastReactionsDeletedTextMultiple" = "Reactions Deleted.";
"Chat.AdminAction.ToastMessagesAndReactionsDeletedText" = "Messages and reactions deleted.";
"Premium.SignUp.SignUpNewInfo" = "Get Telegram Premium for %@";
"Premium.SignUp.SignUpNewInfo.Days_1" = "%@ day";
"Premium.SignUp.SignUpNewInfo.Days_any" = "%@ days";
"Premium.SignUp.SignUpNewInfoNone" = "Get Telegram Premium";
"Login.Fee.Support.NewText.Days_1" = "%@ day";
"Login.Fee.Support.NewText.Days_any" = "%@ days";
"Login.Fee.Support.NewText" = "Sign up for a %@ Telegram Premium subscription to help cover the SMS costs.";
"Login.Fee.Support.NewTextNone" = "Sign up for Telegram Premium subscription to help cover the SMS costs.";
"Login.Fee.GetPremiumNone" = "Get Telegram Premium";
"Login.Fee.GetPremiumForDays" = "Get Telegram Premium for %@";
"Login.Fee.GetPremiumForDays.Days_1" = "%@ day";
"Login.Fee.GetPremiumForDays.Days_any" = "%@ days";
"PeerInfo.DeleteReaction" = "Delete Reaction";
"Chat.DeleteReactionInfo" = "Tap and hold to delete reaction.";
"Chat.AdminActionSheet.DeleteReactionTitle" = "Delete 1 Reaction";
"Chat.AdminActionSheet.DeleteAllMessages" = "Delete All Messages";
"Chat.AdminActionSheet.DeleteAllReactions" = "Delete All Reactions";
"Conversation.CalendarSearch.Title" = "Search";
"Conversation.CalendarSearch.Done" = "Done";
"ScheduleMessage.SilentPosting.YouEnabled" = "You will receive a silent notification";
"ScheduleMessage.SilentPosting.YouDisabled" = "You will be notified";
"ScheduleMessage.SilentPosting.UserEnabled" = "%@ will receive a silent notification";
"ScheduleMessage.SilentPosting.UserDisabled" = "%@ will be notified";
"ScheduleMessage.SilentPosting.GroupEnabled" = "Members will receive a silent notification";
"ScheduleMessage.SilentPosting.GroupDisabled" = "Members will be notified";
"ScheduleMessage.SilentPosting.ChannelEnabled" = "Subscribers will receive a silent notification";
"ScheduleMessage.SilentPosting.ChannelDisabled" = "Subscribers will be notified";
"Settings.ChatAutomation" = "Chat Automation";
"Settings.ChatAutomationInfo" = "Add a bot to reply to messages on your behalf.";
"Settings.ChatAutomationOff" = "Off";
"Chat.SendReactionRestricted" = "You cannot send reactions in this chat.";
"ChatbotSetup.BotInstalled" = "%@ now manages your account.";
"ChatbotSetup.SetupNotCompleted.Title" = "No Bot Added";
"ChatbotSetup.SetupNotCompleted.Text" = "You haven’t added a bot to manage your account. Leave anyway?";
"ChatbotSetup.SetupNotCompleted.Leave" = "Leave";
"Chat.SavedMessagesStatusViewAsChats" = "Tap to view as chats";
"Chat.ToastVoiceMessageDeviceMuted" = "Device is muted.";
"VideoChat.StatusPeerJoined" = "%@ joined";
"VideoChat.StatusPeerLeft" = "%@ left";

16
build-system/BUILD
View file

@ -4,6 +4,22 @@ config_setting(
values = {"cpu": "ios_sim_arm64"},
)
config_setting(
name = "linux_arm64",
constraint_values = [
"@platforms//os:linux",
"@platforms//cpu:aarch64",
],
)
config_setting(
name = "linux_x86_64",
constraint_values = [
"@platforms//os:linux",
"@platforms//cpu:x86_64",
],
)
exports_files([
"GenerateStrings/GenerateStrings.py",
])

983
docs/superpowers/plans/2026-04-16-postbox-to-telegramengine-refactor-wave-1.md
View file

@ -1,983 +0,0 @@
# Postbox → TelegramEngine refactor, wave 1 — Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Drop the direct `import Postbox` dependency from the first 10 leaf consumer submodules (one file each), routing data access through `TelegramEngine` while preserving behavior exactly.
**Architecture:** For each of the 10 modules, apply the same deterministic playbook: inventory every Postbox reference in its single Postbox-importing file, swap bare Postbox type names for their engine typealiases (`PeerId` → `EnginePeer.Id`, etc.), replace imperative Postbox calls with existing engine methods or new thin engine wrappers added to TelegramCore in a preparatory commit, remove `import Postbox` and the Bazel dep, and run the full project build to verify.
**Tech Stack:** Swift, Bazel (primary build system), Postbox (storage lib being made opaque), TelegramCore + TelegramEngine (the public facade), SSignalKit (signals).
**Spec:** [docs/superpowers/specs/2026-04-16-postbox-to-telegramengine-refactor-wave-1-design.md](../specs/2026-04-16-postbox-to-telegramengine-refactor-wave-1-design.md)
---
## Background the executor needs
There are no unit tests in this project (`CLAUDE.md`: "No tests are used at the moment"). **The only verification is the full project build.** Every task ends with a full build that must go green before the next task starts.
### The full build command
Run from the repo root (`/Users/ali/build/telegram/telegram-ios`):
```bash
source ~/.zshrc 2>/dev/null; \
PATH=/opt/homebrew/opt/ruby/bin:`gem environment gemdir`/bin:$PATH \
python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development \
--gitCodesigningUseCurrent \
--buildNumber 1 \
--configuration debug_sim_arm64
```
(`source ~/.zshrc` picks up `TELEGRAM_CODESIGNING_GIT_PASSWORD` and other env exports that the Claude Code bash shell doesn't inherit by default.)
It is slow. Do not shortcut it with `bazel build //submodules/X` — the spec chose full build per module.
### Engine typealias cheat sheet (already in TelegramCore)
When removing `import Postbox`, bare Postbox names in the file must be swapped for their engine equivalents. The ones that exist as typealiases today (confirmed by grep over `submodules/TelegramCore/Sources/TelegramEngine/`):
- `PeerId` → `EnginePeer.Id`
- `MessageId` → `EngineMessage.Id`
- `MessageIndex` → `EngineMessage.Index`
- `MessageTags` → `EngineMessage.Tags`
- `MessageAttribute` → `EngineMessage.Attribute`
- `MessageFlags` → `EngineMessage.Flags`
- `MessageForwardInfo` → `EngineMessage.ForwardInfo`
- `MediaId` → `EngineMedia.Id`
- `PreferencesEntry` → `EnginePreferencesEntry`
- `TempBox` (the singleton helper) → `EngineTempBox`
- `PinnedItemId` → `EngineChatList.PinnedItem.Id`
If a task needs a Postbox type that has **no** existing engine typealias, the task may add one in `TelegramCore` (trivial `public typealias EngineX = X`) in the preparatory commit — this is explicitly allowed by the spec.
### Engine wrapper locations (per the spec)
- Data reads / subscriptions → new `TelegramEngine.EngineData.Item.<Area>.<Name>` in `submodules/TelegramCore/Sources/TelegramEngine/Data/<Area>Data.swift`.
- Imperative signal-returning calls → new method on `Peers` / `Messages` / `Resources` / `AccountData` under `submodules/TelegramCore/Sources/TelegramEngine/<Area>/`.
- Media-resource access → extend `engine.resources` (e.g. `engine.resources.data(...)`, `engine.resources.status(...)`), forwarding to `account.postbox.mediaBox.*` internally.
- Consumer-run `account.postbox.transaction { ... }` → a specific purpose-built engine method. No generic transaction escape hatch.
### Static-check commands (run before the build in every task)
```bash
grep -R "^import Postbox" submodules/<M>/Sources # must return empty
grep "submodules/Postbox" submodules/<M>/BUILD # must return empty
```
### Commit convention
Per module, up to two commits (optional first, required second):
1. `TelegramCore: add <wrapper name>` — only if new engine wrappers were needed.
2. `<ModuleName>: drop direct Postbox dependency` — consumer edits + BUILD change.
Always use a HEREDOC commit body. No `--amend`. Every commit must build.
**TelegramCore wrapper commit template** (used by any task's Step 2a when engine wrappers/typealiases are added):
```bash
git add submodules/TelegramCore/...
git commit -m "$(cat <<'EOF'
TelegramCore: add <wrapper name(s)>
Prepares for <ModuleName> to drop Postbox.
Searched TelegramEngine/ for existing equivalents: <found list, or "not found">.
<one-line summary of what each wrapper exposes>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
### Build-failure handling (applies to every task's Step 6)
When the full build fails after a consumer edit:
- Read the **first** compiler error in the build output.
- If it's a name-resolution or type error in the module file being refactored, fix the mapping in that file and rebuild.
- If it's in a **different** module that depends on the module being refactored, a public signature changed unexpectedly. Either (a) revert that signature change so the public surface stays identical, or (b) if the new surface is genuinely better, extend the fix to the downstream call site **in the same commit**.
- If fixing would require editing a module outside the wave-1 list — or would require aliasing an umbrella type banned by spec rule 2 (`Postbox`, `Account`, `MediaBox`) — revert all changes from the current task and mark the module **Abandoned** in its task body with a one-line reason. Do NOT substitute a different module; the wave's done-count simply goes down by one.
### The 10 modules (from the spec's deterministic selection rule)
Reverse-dep count (over the 30-candidate pool) ascending, alphabetical tiebreak. Verified by running the selection script in Task 0:
1. ActionSheetPeerItem — **ABANDONED** (see Task 1 body). Public init takes `postbox: Postbox`; ShareController caller is out-of-wave.
2. ChatInterfaceState — `submodules/ChatInterfaceState/Sources/ChatInterfaceState.swift` — DONE
3. ChatListSearchRecentPeersNode — **ABANDONED** (see Task 3 body). Public init takes `postbox: Postbox`; ShareController + ChatListUI callers are out-of-wave.
4. ChatSendMessageActionUI — `submodules/ChatSendMessageActionUI/Sources/ChatSendMessageContextScreen.swift`
5. ContactListUI — `submodules/ContactListUI/Sources/ContactListNode.swift`
6. DirectMediaImageCache — **ABANDONED** (see Task 6 body). Public init takes `account: Account`; six out-of-wave callers.
7. DrawingUI — `submodules/DrawingUI/Sources/DrawingScreen.swift`
8. FetchManagerImpl — **ABANDONED** (see Task 8 body). Public init takes `postbox: Postbox`; TelegramUI caller is out-of-wave.
9. GalleryData — **ABANDONED** (see Task 9 body). Four public functions take `Media`/`Message` as parameters; refactor cascades into many out-of-wave downstream types (`AvatarGalleryEntry`, `MessageReference`, etc.). Good candidate for a bespoke future wave that migrates the domain types together.
10. ICloudResources — **ABANDONED** (see Task 10 body). Class conforms to `TelegramMediaResource` and inherits `isEqual(to: MediaResource)`; overriding that without aliasing the `MediaResource` protocol isn't possible.
**Wave-1 done-count: 4** (Tasks 2, 4, 5, 7 done; Tasks 1, 3, 6, 8, 9, 10 abandoned).
Per the spec's **abandonment protocol**, if a module hits an unresolvable blocker (requires aliasing an umbrella type such as `Postbox`/`Account`/`MediaBox`, or requires editing a module outside the wave-1 list), it is marked Abandoned in its task body and **not substituted**. The wave's done-count goes down by one; fallback modules are not pulled into the wave mid-execution. A later wave can revisit the abandoned module with tools not available in wave 1 (e.g. a real engine wrapper rather than a typealias, or a refactor that migrates the caller first).
---
## Task 0: Verify selection and baseline build
**Files:**
- Read: `submodules/<each module>/BUILD`
- [ ] **Step 1: Re-run the selection script to confirm the 10**
Save and run this Python snippet from the repo root. It should output exactly the 10 modules listed above, in that order.
```bash
python3 <<'EOF'
import os, re
pool = ["ActionSheetPeerItem","ChatInterfaceState","ChatListSearchRecentPeersNode","ChatSendMessageActionUI","ContactListUI","DirectMediaImageCache","DrawingUI","FetchManagerImpl","GalleryData","HorizontalPeerItem","ICloudResources","InAppPurchaseManager","InstantPageCache","InviteLinksUI","ItemListAvatarAndNameInfoItem","ItemListPeerItem","ItemListStickerPackItem","MapResourceToAvatarSizes","PhotoResources","PlatformRestrictionMatching","PresentationDataUtils","PromptUI","SaveToCameraRoll","SelectablePeerNode","ShareItems","SoftwareVideo","StickerPeekUI","StickerResources","TelegramIntents","TelegramNotices"]
deps = {}
for m in pool:
p = f"submodules/{m}/BUILD"
txt = open(p).read() if os.path.exists(p) else ""
deps[m] = {o for o in pool if o != m and re.search(rf'//submodules/{re.escape(o)}(:|"|$)', txt)}
rdep = {m:0 for m in pool}
for m,ds in deps.items():
for d in ds: rdep[d]+=1
for m in sorted(pool, key=lambda m:(rdep[m],m))[:10]:
print(m, rdep[m])
EOF
```
Expected output (one per line): `ActionSheetPeerItem 0`, `ChatInterfaceState 0`, `ChatListSearchRecentPeersNode 0`, `ChatSendMessageActionUI 0`, `ContactListUI 0`, `DirectMediaImageCache 0`, `DrawingUI 0`, `FetchManagerImpl 0`, `GalleryData 0`, `ICloudResources 0`.
If the output differs, stop and investigate — someone changed a BUILD file since the spec was written.
- [ ] **Step 2: Run the baseline full build**
Run the full build command above. Expected: PASS (green master). If it fails, stop — we need a green baseline before changing anything. Do not attempt to fix pre-existing build breakage as part of this plan.
- [ ] **Step 3: No commit**
Task 0 produces no code changes.
---
## Task 1: Refactor `ActionSheetPeerItem` — **ABANDONED**
**Status:** Abandoned for wave 1. No code changes in this repo from this task.
**Reason:** Refactoring this module requires either (a) typealiasing the `Postbox` class itself (banned — see spec §Guiding rules rule 2: umbrella-type typealiases rename without encapsulating) or (b) editing `submodules/ShareController/` which is not in the wave-1 list. The module's designated init takes `postbox: Postbox` as a parameter and its sole out-of-wave caller (ShareController) passes `info.account.stateManager.postbox` directly, so there is no path to drop the `import Postbox` here without crossing the wave boundary or violating rule 2. Per the spec's **abandonment protocol**, the module is skipped for this wave. Wave-1 done-count is therefore 9, not 10.
**Original task body (retained for audit trail, do not implement):**
**Files:**
- Modify: `submodules/ActionSheetPeerItem/Sources/ActionSheetPeerItem.swift`
- Modify: `submodules/ActionSheetPeerItem/BUILD`
**Starting inventory** (computed during planning):
Grep for common Postbox API/type names in `ActionSheetPeerItem.swift` returned zero hits on `mediaBox`, `transaction`, `PostboxView`, `combinedView`, `PeerId`, `MessageId`, `MediaResource`, `CachedPeerData`, etc. The `import Postbox` line appears unused. Confirm this during inventory — it's the most likely case, but other Postbox symbols (e.g. types referenced inside a parameter type) may still be present. (Subsequent inventory discovered the module does take `postbox: Postbox` as a parameter type — this is what makes the module unrefactorable under the wave-1 rules.)
- [ ] **Step 1: Inventory**
Read `submodules/ActionSheetPeerItem/Sources/ActionSheetPeerItem.swift` top to bottom. Record every identifier that is Postbox-owned. If the inventory is empty, skip straight to Step 4.
Run this helper grep too:
```bash
grep -nE "\b(PeerId|MessageId|MessageIndex|MessageTags|MessageAttribute|MessageFlags|Peer|Media|MediaId|MediaResource|PostboxView|CachedPeerData|PreferencesEntry|ChatListIndex|PeerReference|TelegramMediaFile|TelegramMediaImage|Namespaces|TempBox)\b" submodules/ActionSheetPeerItem/Sources/ActionSheetPeerItem.swift
```
- [ ] **Step 2: Map each reference to a replacement**
For each finding from Step 1, decide: existing engine typealias (see cheat sheet), existing engine method, existing TelegramCore non-Postbox export, or new engine wrapper. Record the mapping in your working notes. If a new wrapper is needed, it is added in Task 1a before Task 1 continues.
- [ ] **Step 2a: (Only if Step 2 identified a missing engine wrapper/typealias) Add to TelegramCore**
Edit the relevant file under `submodules/TelegramCore/Sources/TelegramEngine/<Area>/` or `submodules/TelegramCore/Sources/TelegramEngine/Data/<Area>Data.swift`, following the wrapper-location rules in the Background section. Keep the wrapper minimal: a single typealias for name-only adds, or a thin method that forwards to the underlying Postbox call for imperative ones.
Run the full build. It must pass. Commit:
```bash
git add submodules/TelegramCore/...
git commit -m "$(cat <<'EOF'
TelegramCore: add <wrapper name>
Prepares for ActionSheetPeerItem to drop Postbox.
<one-line summary of what the wrapper exposes>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
Skip this step if Step 2 didn't identify any missing wrappers.
- [ ] **Step 3: Edit the consumer file**
In `submodules/ActionSheetPeerItem/Sources/ActionSheetPeerItem.swift`:
- Apply every mapping from Step 2.
- Remove the line `import Postbox`.
- [ ] **Step 4: Drop the Bazel dep**
Edit `submodules/ActionSheetPeerItem/BUILD`. Remove the line `"//submodules/Postbox:Postbox",` from the `deps` array. Leave the rest of the BUILD untouched.
- [ ] **Step 5: Static checks**
Run:
```bash
grep -R "^import Postbox" submodules/ActionSheetPeerItem/Sources # expect: empty
grep "submodules/Postbox" submodules/ActionSheetPeerItem/BUILD # expect: empty
```
Both must return no output. If either produces a hit, go back to Step 3 or Step 4.
- [ ] **Step 6: Full project build**
Run the full build command from the Background section. Expected: PASS.
If it fails:
- Read the first error. If it's a name-resolution error in `ActionSheetPeerItem.swift`, fix the mapping and rebuild.
- If it's in a *different* module that depends on `ActionSheetPeerItem`, you changed a public signature unexpectedly; either revert that signature change or, if it's genuinely better, extend the fix to that downstream call site in the same commit.
- If the fix would require editing a module outside the wave-1 list, revert all Task 1 changes and skip to the next fallback module listed in the Background section.
- [ ] **Step 7: Commit**
```bash
git add submodules/ActionSheetPeerItem/
git commit -m "$(cat <<'EOF'
ActionSheetPeerItem: drop direct Postbox dependency
Route data access through TelegramEngine/TelegramCore; remove the
Postbox import and Bazel dep. Behavior-preserving.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 2: Refactor `ChatInterfaceState`
**Files:**
- Modify: `submodules/ChatInterfaceState/Sources/ChatInterfaceState.swift`
- Modify: `submodules/ChatInterfaceState/BUILD`
**Starting inventory** (computed during planning): file references `MessageId` (×2) and `MediaResource` (×3). No `mediaBox`, `transaction`, `combinedView`, or `PostboxView` usage. This is a **type-reference-only** case — expected replacements are `MessageId` → `EngineMessage.Id` and `MediaResource` stays as-is only if a typealias exists, otherwise a typealias `EngineMediaResource = MediaResource` is added in TelegramCore.
- [ ] **Step 1: Inventory**
Read `submodules/ChatInterfaceState/Sources/ChatInterfaceState.swift`. Confirm the grep below matches the planning inventory and records exact line numbers and declaration contexts (parameter types, property types, return types, generic arguments).
```bash
grep -nE "\b(PeerId|MessageId|MessageIndex|MessageTags|MessageAttribute|MessageFlags|Peer|Media|MediaId|MediaResource|PostboxView|CachedPeerData|PreferencesEntry|ChatListIndex|PeerReference|TelegramMediaFile|TelegramMediaImage|Namespaces|TempBox)\b" submodules/ChatInterfaceState/Sources/ChatInterfaceState.swift
```
- [ ] **Step 2: Map each reference**
- `MessageId` → `EngineMessage.Id` (existing typealias, no wrapper needed).
- `MediaResource`: search `submodules/TelegramCore/Sources/TelegramEngine/` for a `public typealias Engine.*Resource.*= MediaResource`. If present, use it. If absent, proceed to Step 2a and add a typealias `public typealias EngineMediaResource = MediaResource` in `submodules/TelegramCore/Sources/TelegramEngine/Resources/` (new file `EngineMediaResource.swift`, or the most natural existing file in that folder).
- [ ] **Step 2a: (Only if needed) Add engine typealias(es) in TelegramCore**
For each Postbox type without an engine typealias, add a `public typealias Engine<Name> = <PostboxName>` in the appropriate TelegramEngine area file. Do not introduce any new wrapper structs.
Run full build, expect PASS. Commit:
```bash
git add submodules/TelegramCore/...
git commit -m "$(cat <<'EOF'
TelegramCore: add engine typealiases for <list>
Prepares for ChatInterfaceState to drop Postbox.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 3: Edit the consumer file**
Apply the mappings from Step 2 to every reference. Remove the line `import Postbox`.
- [ ] **Step 4: Drop the Bazel dep**
Edit `submodules/ChatInterfaceState/BUILD`. Remove `"//submodules/Postbox:Postbox",` from `deps`.
- [ ] **Step 5: Static checks**
```bash
grep -R "^import Postbox" submodules/ChatInterfaceState/Sources # expect: empty
grep "submodules/Postbox" submodules/ChatInterfaceState/BUILD # expect: empty
```
- [ ] **Step 6: Full project build**
Run the full build command. Expected: PASS. Handle failures per the rules in Task 1 Step 6.
- [ ] **Step 7: Commit**
```bash
git add submodules/ChatInterfaceState/
git commit -m "$(cat <<'EOF'
ChatInterfaceState: drop direct Postbox dependency
Switch remaining Postbox-typed references to engine typealiases;
remove the Postbox import and Bazel dep. Behavior-preserving.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 3: Refactor `ChatListSearchRecentPeersNode` — **ABANDONED**
**Status:** Abandoned for wave 1. No code changes in this repo from this task.
**Reason:** The module's public `init` at line 207 takes `postbox: Postbox` as a parameter. Two out-of-wave callers (`submodules/ShareController/Sources/ShareControllerRecentPeersGridItem.swift`, `submodules/ChatListUI/Sources/ChatListRecentPeersListItem.swift`) use this init. Refactoring requires either typealiasing the `Postbox` class (banned by spec rule 2) or editing those two out-of-wave modules (banned by wave boundary). Per the abandonment protocol, the module is skipped.
**Original task body (retained for audit trail, do not implement):**
**Files:**
- Modify: `submodules/ChatListSearchRecentPeersNode/Sources/ChatListSearchRecentPeersNode.swift`
- Modify: `submodules/ChatListSearchRecentPeersNode/BUILD`
**Starting inventory** (computed during planning): file uses `postbox.transaction { ... }` (×2), `postbox.combinedView(...)` (×1), and references `TelegramMedia*` types (×3). This is the **first hard module** in the wave — it has real imperative Postbox calls that require engine wrappers, not just typealiases.
- [ ] **Step 1: Inventory**
Read the whole file. For each Postbox call, capture:
- The call site (line number, containing function).
- The `PostboxViewKey`(s) passed to `combinedView`.
- What the closure body of each `transaction` does — the *intent*, not just the code. (This determines which engine method to add.)
Run:
```bash
grep -nE "\b(postbox\.|mediaBox|transaction\s*\{|combinedView|PostboxView|PostboxViewKey|Namespaces\.|TelegramMedia|PeerId|MessageId)\b" submodules/ChatListSearchRecentPeersNode/Sources/ChatListSearchRecentPeersNode.swift
```
- [ ] **Step 2: Map each reference**
- `TelegramMedia*` — these classes are defined in `TelegramCore` (check `submodules/TelegramCore/Sources/`), not Postbox. After `import Postbox` is removed they remain reachable via `import TelegramCore`, which the file already imports. No action beyond confirming.
- Each `postbox.combinedView` / view subscription → map to an existing `TelegramEngine.data.subscribe(...)` item if one exists for the same `PostboxViewKey`; if not, add an `EngineData.Item` under `submodules/TelegramCore/Sources/TelegramEngine/Data/<Area>Data.swift`.
- Each `postbox.transaction { ... }` → a specific new method on the matching engine area (e.g. `TelegramEngine.Peers.recordRecentPeer(id:)` if that's what the closure does). Do **not** add a generic transaction passthrough.
Write the mapping down before editing. Each new engine method is small and focused.
- [ ] **Step 2a: Add engine wrappers in TelegramCore**
For each new `EngineData.Item` or engine method identified in Step 2:
- Add it to the appropriate file under `submodules/TelegramCore/Sources/TelegramEngine/<Area>/` (or `…/Data/<Area>Data.swift` for data items).
- Keep the body to a minimal pass-through: the new engine method opens a transaction internally and calls the same Postbox code that the consumer was running; the new `EngineData.Item` forwards a `PostboxViewKey` in `keys()` and extracts its `PostboxView` in `extract()`.
- Return engine-typed values where existing engine types are available; otherwise return primitives or `Void`. Do not return bare Postbox types.
Before editing TelegramCore, grep for existing wrappers covering the same need:
```bash
grep -rn "<plausible method name>\|<PostboxViewKey case>" submodules/TelegramCore/Sources/TelegramEngine/
```
Record "searched for X, found/not found" in the commit message.
Run the full build. Expected: PASS.
Commit:
```bash
git add submodules/TelegramCore/...
git commit -m "$(cat <<'EOF'
TelegramCore: add <wrapper name(s)>
Prepares for ChatListSearchRecentPeersNode to drop Postbox.
Searched TelegramEngine/ for existing equivalents: not found.
<one-line summary of what each wrapper exposes>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 3: Edit the consumer file**
Replace each `postbox.transaction` and `postbox.combinedView` call with the engine method/subscription added in Step 2a. Swap any Postbox-typed names for engine typealiases per the cheat sheet. Remove `import Postbox`.
- [ ] **Step 4: Drop the Bazel dep**
Edit `submodules/ChatListSearchRecentPeersNode/BUILD`. Remove `"//submodules/Postbox:Postbox",` from `deps`.
- [ ] **Step 5: Static checks**
```bash
grep -R "^import Postbox" submodules/ChatListSearchRecentPeersNode/Sources # expect: empty
grep "submodules/Postbox" submodules/ChatListSearchRecentPeersNode/BUILD # expect: empty
```
- [ ] **Step 6: Full project build**
Run the full build command. Expected: PASS. Handle failures per the Build-failure handling rules in the Background section.
- [ ] **Step 7: Commit**
```bash
git add submodules/ChatListSearchRecentPeersNode/
git commit -m "$(cat <<'EOF'
ChatListSearchRecentPeersNode: drop direct Postbox dependency
Route combined-view subscription and transactions through
TelegramEngine; remove the Postbox import and Bazel dep.
Behavior-preserving.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 4: Refactor `ChatSendMessageActionUI`
**Files:**
- Modify: `submodules/ChatSendMessageActionUI/Sources/ChatSendMessageContextScreen.swift`
- Modify: `submodules/ChatSendMessageActionUI/BUILD`
**Starting inventory** (computed during planning): `mediaBox` (×2), `Peer` type reference (×1), `Media` type reference (×1), `MediaResource` (×1), `Namespaces.` (×1). The mediaBox calls are the substantive work.
- [ ] **Step 1: Inventory**
Read the whole file. Capture every `mediaBox` call — what resource is being asked for and what is done with the result (data read, status subscription, fetch start, path access)? Capture each Postbox-typed reference's line/context.
```bash
grep -nE "\bmediaBox\b|\bNamespaces\.|\b(Peer|Media|MediaResource)\b" submodules/ChatSendMessageActionUI/Sources/ChatSendMessageContextScreen.swift
```
- [ ] **Step 2: Map each reference**
- Each `mediaBox.<op>` call → `engine.resources.<equivalent>(...)`. Check for an existing method on `TelegramEngine.Resources` first:
```bash
grep -rn "extension.*Resources\|public func" submodules/TelegramCore/Sources/TelegramEngine/Resources/
```
If an equivalent exists, use it. If not, add one in Step 2a.
- `Peer`, `Media`, `MediaResource` type references → use `EnginePeer`, `EngineMedia`, or `EngineMediaResource` (add typealias if missing, per the cheat sheet).
- `Namespaces.Peer.<case>` — defined in TelegramCore, not Postbox. Confirm via grep; no change needed.
- [ ] **Step 2a: (Only if needed) Add engine wrappers in TelegramCore**
Per the rules — minimal pass-through, return engine-typed values. Build, commit `TelegramCore: add <name>` per the template in Task 3 Step 2a.
- [ ] **Step 3: Edit the consumer file**
Apply mappings. Remove `import Postbox`.
- [ ] **Step 4: Drop the Bazel dep**
Edit `submodules/ChatSendMessageActionUI/BUILD`. Remove `"//submodules/Postbox:Postbox",` from `deps`.
- [ ] **Step 5: Static checks**
```bash
grep -R "^import Postbox" submodules/ChatSendMessageActionUI/Sources # expect: empty
grep "submodules/Postbox" submodules/ChatSendMessageActionUI/BUILD # expect: empty
```
- [ ] **Step 6: Full project build**
Run the full build. Expected: PASS. Handle failures per the Build-failure handling rules in the Background section.
- [ ] **Step 7: Commit**
```bash
git add submodules/ChatSendMessageActionUI/
git commit -m "$(cat <<'EOF'
ChatSendMessageActionUI: drop direct Postbox dependency
Route MediaBox calls through TelegramEngine.resources and switch
type references to engine typealiases; remove the Postbox import
and Bazel dep. Behavior-preserving.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 5: Refactor `ContactListUI`
**Files:**
- Modify: `submodules/ContactListUI/Sources/ContactListNode.swift`
- Modify: `submodules/ContactListUI/BUILD`
**Starting inventory** (computed during planning): `postbox.transaction { ... }` (×4), `Peer` references (×15), `Namespaces.` (×1). Transactions are the substantive work; the 15 `Peer` references are likely in closures reading transaction state and will switch to engine-typed returns once the transactions are replaced.
- [ ] **Step 1: Inventory**
Read the whole file. For each `transaction` call, describe what the closure does — this drives what new engine methods to add. Capture every `Peer`-typed declaration.
```bash
grep -nE "\btransaction\s*\{|account\.postbox|\b(Peer|PeerId|Namespaces)\b" submodules/ContactListUI/Sources/ContactListNode.swift
```
- [ ] **Step 2: Map each reference**
- Each `postbox.transaction { ... }` → a dedicated engine method under `submodules/TelegramCore/Sources/TelegramEngine/{Peers,Contacts,AccountData}/` capturing the closure's intent. Never add a generic transaction passthrough.
- `Peer` type → `EnginePeer` where the value actually flows through the replaced engine method (the engine method should return `EnginePeer` / `[EnginePeer]`). For local variable types that receive the engine-method return, use the engine type.
- `Namespaces.*` — defined in TelegramCore. No change.
Before adding methods, grep for existing engine functions that may already cover the intent:
```bash
grep -rn "public func" submodules/TelegramCore/Sources/TelegramEngine/Contacts/
grep -rn "public func" submodules/TelegramCore/Sources/TelegramEngine/Peers/ | head -60
```
- [ ] **Step 2a: Add engine wrappers in TelegramCore**
Add each new method. Return engine-typed values. Build; then use the TelegramCore wrapper commit template from the Background section.
- [ ] **Step 3: Edit the consumer file**
Replace every `transaction` call with its engine method. Switch `Peer` locals to `EnginePeer`. Remove `import Postbox`.
- [ ] **Step 4: Drop the Bazel dep**
Edit `submodules/ContactListUI/BUILD`. Remove `"//submodules/Postbox:Postbox",` from `deps`.
- [ ] **Step 5: Static checks**
```bash
grep -R "^import Postbox" submodules/ContactListUI/Sources # expect: empty
grep "submodules/Postbox" submodules/ContactListUI/BUILD # expect: empty
```
- [ ] **Step 6: Full project build**
Run the full build. Expected: PASS. Handle failures per the Build-failure handling rules in the Background section. ContactListUI is imported by other submodules (TelegramUI, SettingsUI, etc.); downstream breakage is most likely here. If a downstream consumer needs a bare `Peer`, either keep the public surface returning engine types (preferred — they're typealiases under the hood) or, if the downstream change is large, revert Task 5 and skip.
- [ ] **Step 7: Commit**
```bash
git add submodules/ContactListUI/
git commit -m "$(cat <<'EOF'
ContactListUI: drop direct Postbox dependency
Replace direct postbox.transaction calls with dedicated engine
methods; switch peer references to engine-typed equivalents;
remove the Postbox import and Bazel dep. Behavior-preserving.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 6: Refactor `DirectMediaImageCache` — **ABANDONED**
**Status:** Abandoned for wave 1. No code changes in this repo from this task.
**Reason:** The module's public `init(account: Account)` at line 241 takes `account: Account` (an umbrella type banned by spec rule 2). Out-of-wave callers include `submodules/CalendarMessageScreen/`, four TelegramUI components (`StoryContainerScreen`, `ShareWithPeersScreen`, `PeerInfoVisualMediaPaneNode` × 2), and `submodules/TelegramUI/Sources/AccountContext.swift`. Refactoring requires either aliasing `Account` (banned) or editing all those out-of-wave callers (banned). Per the abandonment protocol, the module is skipped.
**Original task body (retained for audit trail, do not implement):**
**Files:**
- Modify: `submodules/DirectMediaImageCache/Sources/DirectMediaImageCache.swift`
- Modify: `submodules/DirectMediaImageCache/BUILD`
**Starting inventory** (computed during planning): `mediaBox` (×11), `PeerReference` (×6), `MediaResource` (×1), `TelegramMedia*` (×13), `Media`/`Message` type references. This module is **mediaBox-heavy** and is the canonical shape for the `engine.resources.*` extension work.
- [ ] **Step 1: Inventory**
Read the whole file. For each `mediaBox` call, record the method (`resourceData`, `resourceStatus`, `cachedResourceRepresentation`, `storeCachedResourceRepresentation`, `fetchedResource`, etc.) and whether it reads, writes, or subscribes.
```bash
grep -nE "\bmediaBox\b|\b(PeerReference|MediaResource|TelegramMedia)" submodules/DirectMediaImageCache/Sources/DirectMediaImageCache.swift
```
- [ ] **Step 2: Map each reference**
Each distinct `mediaBox.<op>` signature → a method on `TelegramEngine.Resources`. Expected additions (names are suggestions — match existing naming if anything close already exists):
- `engine.resources.data(_:pathExtension:option:attemptSynchronously:) -> Signal<MediaResourceData, NoError>`
- `engine.resources.status(_:approximateSynchronousValue:) -> Signal<MediaResourceStatus, NoError>`
- `engine.resources.cachedRepresentationData(_:representation:complete:) -> Signal<...>`
- `engine.resources.storeCachedRepresentation(_:representation:data:) -> Signal<Void, NoError>`
Before adding any of these, grep `submodules/TelegramCore/Sources/TelegramEngine/Resources/` for existing equivalents and only add what's missing.
`PeerReference`, `TelegramMedia*`, `MediaResource` — check each: `TelegramMedia*` types live in `TelegramCore` (not Postbox). `PeerReference` lives in `TelegramCore`. `MediaResource` is a Postbox protocol; add `EngineMediaResource = MediaResource` typealias if not already present.
- [ ] **Step 2a: Add engine wrappers in TelegramCore**
Add all missing methods on `Resources` and any missing typealiases. Each method is a one-line forward to `account.postbox.mediaBox.*`. Build; then commit using the TelegramCore wrapper commit template from the Background section, recording "searched Resources/ for equivalents: found/not found" in the message.
- [ ] **Step 3: Edit the consumer file**
Replace every `mediaBox.*` with `engine.resources.*`. This likely requires adding an `engine: TelegramEngine` parameter to a few internal functions in the file (or surfacing it from an existing `AccountContext` already in scope — prefer that). Switch types to engine typealiases. Remove `import Postbox`.
- [ ] **Step 4: Drop the Bazel dep**
Edit `submodules/DirectMediaImageCache/BUILD`. Remove `"//submodules/Postbox:Postbox",` from `deps`.
- [ ] **Step 5: Static checks**
```bash
grep -R "^import Postbox" submodules/DirectMediaImageCache/Sources # expect: empty
grep "submodules/Postbox" submodules/DirectMediaImageCache/BUILD # expect: empty
```
- [ ] **Step 6: Full project build**
Run the full build. Expected: PASS. Handle failures per the Build-failure handling rules in the Background section.
- [ ] **Step 7: Commit**
```bash
git add submodules/DirectMediaImageCache/
git commit -m "$(cat <<'EOF'
DirectMediaImageCache: drop direct Postbox dependency
Route MediaBox calls through TelegramEngine.resources; remove the
Postbox import and Bazel dep. Behavior-preserving.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 7: Refactor `DrawingUI`
**Files:**
- Modify: `submodules/DrawingUI/Sources/DrawingScreen.swift`
- Modify: `submodules/DrawingUI/BUILD`
**Starting inventory** (computed during planning): `transaction` (×3), `Media` type references (×13), `Namespaces.` (×4). Transactions are the substantive work; `Media`/`Namespaces` are mostly referencing TelegramCore-defined types already.
- [ ] **Step 1: Inventory**
Read the whole file. For each `transaction` call, describe what the closure does. Capture every `Media`-typed declaration and every `Namespaces.*` reference.
```bash
grep -nE "\btransaction\s*\{|account\.postbox|\b(Media|MediaId|Namespaces)\b" submodules/DrawingUI/Sources/DrawingScreen.swift
```
- [ ] **Step 2: Map each reference**
- Each `postbox.transaction` → dedicated engine method. Inspect the closure to find the right home (`Stickers`, `Messages`, `Peers`, …).
- `Media` → `EngineMedia` where the value flows through new engine methods; keep as `Media` (TelegramCore re-defined concrete classes like `TelegramMediaFile` live in TelegramCore and are fine) where the type is already TelegramCore's.
- `Namespaces.*` — TelegramCore. No change.
- [ ] **Step 2a: Add engine wrappers in TelegramCore**
Add each new transaction-replacing method. Build; then use the TelegramCore wrapper commit template from the Background section.
- [ ] **Step 3: Edit the consumer file**
Apply mappings. Remove `import Postbox`.
- [ ] **Step 4: Drop the Bazel dep**
Edit `submodules/DrawingUI/BUILD`. Remove `"//submodules/Postbox:Postbox",` from `deps`.
- [ ] **Step 5: Static checks**
```bash
grep -R "^import Postbox" submodules/DrawingUI/Sources # expect: empty
grep "submodules/Postbox" submodules/DrawingUI/BUILD # expect: empty
```
- [ ] **Step 6: Full project build**
Run the full build. Expected: PASS. Handle failures per the Build-failure handling rules in the Background section.
- [ ] **Step 7: Commit**
```bash
git add submodules/DrawingUI/
git commit -m "$(cat <<'EOF'
DrawingUI: drop direct Postbox dependency
Replace direct postbox.transaction calls with dedicated engine
methods; switch type references to engine equivalents; remove the
Postbox import and Bazel dep. Behavior-preserving.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 8: Refactor `FetchManagerImpl` — **ABANDONED**
**Status:** Abandoned for wave 1. No code changes in this repo from this task.
**Reason:** The module's public `init(postbox: Postbox, storeManager: DownloadedMediaStoreManager?)` at line 708 takes `postbox: Postbox`. Out-of-wave caller: `submodules/TelegramUI/Sources/AccountContext.swift:296`. Refactoring requires either aliasing the `Postbox` class (banned by spec rule 2) or editing TelegramUI (banned by wave boundary). Per the abandonment protocol, the module is skipped.
**Original task body (retained for audit trail, do not implement):**
**Files:**
- Modify: `submodules/FetchManagerImpl/Sources/FetchManagerImpl.swift`
- Modify: `submodules/FetchManagerImpl/BUILD`
**Starting inventory** (computed during planning): `mediaBox` (×8), `MediaResource` (×4), `TelegramMedia` (×1). Shape is similar to DirectMediaImageCache — heavy `mediaBox` usage, no transactions.
- [ ] **Step 1: Inventory**
Read the whole file. For each `mediaBox` call, record the method and direction (read / subscribe / fetch-start).
```bash
grep -nE "\bmediaBox\b|\b(MediaResource|TelegramMedia)\b" submodules/FetchManagerImpl/Sources/FetchManagerImpl.swift
```
- [ ] **Step 2: Map each reference**
Reuse every `engine.resources.*` method added in Task 6 — do not re-add them. Grep:
```bash
grep -rn "extension.*Resources\|public func" submodules/TelegramCore/Sources/TelegramEngine/Resources/
```
If this task needs a `mediaBox` operation that Task 6 did not add (e.g. `cancelInteractiveResourceFetch`, `completeInteractiveResourceFetch`), add it now in the same pattern.
`MediaResource` → `EngineMediaResource` typealias (already added in an earlier task if needed). `TelegramMedia` — TelegramCore type, no change.
- [ ] **Step 2a: (Only if needed) Add missing engine methods**
Minimal pass-through on `TelegramEngine.Resources`. Build, commit.
- [ ] **Step 3: Edit the consumer file**
Replace every `mediaBox.*` with `engine.resources.*`. Thread an `engine` argument through internal functions as needed (prefer reading it off an existing `AccountContext` already in scope). Remove `import Postbox`.
- [ ] **Step 4: Drop the Bazel dep**
Edit `submodules/FetchManagerImpl/BUILD`. Remove `"//submodules/Postbox:Postbox",` from `deps`.
- [ ] **Step 5: Static checks**
```bash
grep -R "^import Postbox" submodules/FetchManagerImpl/Sources # expect: empty
grep "submodules/Postbox" submodules/FetchManagerImpl/BUILD # expect: empty
```
- [ ] **Step 6: Full project build**
Run the full build. Expected: PASS. Handle failures per the Build-failure handling rules in the Background section.
- [ ] **Step 7: Commit**
```bash
git add submodules/FetchManagerImpl/
git commit -m "$(cat <<'EOF'
FetchManagerImpl: drop direct Postbox dependency
Route MediaBox fetch/status calls through TelegramEngine.resources;
remove the Postbox import and Bazel dep. Behavior-preserving.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 9: Refactor `GalleryData` — **ABANDONED**
**Status:** Abandoned for wave 1. No code changes in this repo from this task.
**Reason:** Four public functions take `Media` (Postbox protocol) and/or `Message` (Postbox class) as parameters, called from TelegramUI and ChatListUI (out-of-wave). Refactoring to `EngineMedia` / `EngineMessage` requires `.init(_:)` / `._asMedia()` / `._asMessage()` coercions threaded through many local variables (e.g. `var galleryMedia: Media?` in `chatMessageGalleryControllerData` is reassigned from various `TelegramMedia*` casts and passed to `MessageReference(...)` chains and enum cases), which would cascade into `AvatarGalleryEntry`, `MessageReference`, and other out-of-wave types. The narrow-utility alias path is ruled out because `Media` and especially `Message` are domain types, not utilities. Per the abandonment protocol, the module is skipped.
**Original task body (retained for audit trail, do not implement):**
**Files:**
- Modify: `submodules/GalleryData/Sources/GalleryData.swift`
- Modify: `submodules/GalleryData/BUILD`
**Starting inventory** (computed during planning): `Peer` (×1), `Media` (×9), `Message` (×4), `Namespaces.` (×3), `TelegramMedia*` (×30). No `mediaBox`, no `transaction`, no `combinedView`. This is a **type-reference-only** case at scale.
- [ ] **Step 1: Inventory**
Read the whole file. Record every declaration that uses a Postbox-owned type (`Peer`, `Media`, `Message`, `MessageId`, etc.) — note that `TelegramMedia*` and `Namespaces` are TelegramCore, not Postbox, and do **not** need changing.
```bash
grep -nE "\b(Peer|Media|Message|MessageId|MessageIndex)\b" submodules/GalleryData/Sources/GalleryData.swift | head -60
```
- [ ] **Step 2: Map each reference**
- `Peer` → `EnginePeer` at the call-site level where the value is newly produced; for existing public signatures that already accept a `Peer` from elsewhere, prefer `EnginePeer` **only if** downstream consumers accept it. Otherwise leave the signature alone and swap only the internal uses.
- `Media`, `Message`, `MessageId` → engine typealiases per the cheat sheet.
- `TelegramMedia*`, `Namespaces.*` — no change.
- [ ] **Step 2a: (Only if needed) Add engine typealiases**
Add any missing typealias in `submodules/TelegramCore/Sources/TelegramEngine/…`. Build, commit.
- [ ] **Step 3: Edit the consumer file**
Apply mappings. Remove `import Postbox`.
- [ ] **Step 4: Drop the Bazel dep**
Edit `submodules/GalleryData/BUILD`. Remove `"//submodules/Postbox:Postbox",` from `deps`.
- [ ] **Step 5: Static checks**
```bash
grep -R "^import Postbox" submodules/GalleryData/Sources # expect: empty
grep "submodules/Postbox" submodules/GalleryData/BUILD # expect: empty
```
- [ ] **Step 6: Full project build**
Run the full build. Expected: PASS. Handle failures per the Build-failure handling rules in the Background section.
- [ ] **Step 7: Commit**
```bash
git add submodules/GalleryData/
git commit -m "$(cat <<'EOF'
GalleryData: drop direct Postbox dependency
Switch Postbox-typed references to engine typealiases; remove the
Postbox import and Bazel dep. Behavior-preserving.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 10: Refactor `ICloudResources` — **ABANDONED**
**Status:** Abandoned for wave 1. No code changes in this repo from this task.
**Reason:** The module declares `public class ICloudFileResource: TelegramMediaResource` and thus must implement `func isEqual(to: MediaResource) -> Bool` (protocol requirement inherited from `MediaResource`). That override's parameter type is fixed at `MediaResource`, which can only be named by importing Postbox or adding a typealias for the raw `MediaResource` protocol. The protocol-alias would be borderline per rule 2; user directed to skip. Per the abandonment protocol, the module is skipped.
**Original task body (retained for audit trail, do not implement):**
### Original Task 10
**Files:**
- Modify: `submodules/ICloudResources/Sources/ICloudResources.swift`
- Modify: `submodules/ICloudResources/BUILD`
**Starting inventory** (computed during planning): `MediaResource` (×2), `TelegramMedia` (×1). No `mediaBox`, no `transaction`. Small type-reference-only module. The `MediaResource` uses may be a custom `MediaResource`-conforming class defined in this file — confirm during inventory.
- [ ] **Step 1: Inventory**
Read the whole file. `MediaResource` is a Postbox protocol; `ICloudResources` likely declares a custom class conforming to it. Capture whether (a) the file declares new `MediaResource`-conforming types, (b) it only references the protocol, or both.
```bash
grep -nE "\b(MediaResource|TelegramMedia)\b|class.*:.*MediaResource|struct.*:.*MediaResource" submodules/ICloudResources/Sources/ICloudResources.swift
```
- [ ] **Step 2: Map each reference**
- If the file declares a type conforming to `MediaResource`, use the `EngineMediaResource` typealias in the declaration (`class FooResource: EngineMediaResource { ... }`). Because typealiases are transparent, this keeps protocol conformance identical.
- All other `MediaResource` references → `EngineMediaResource`.
- `TelegramMedia*` — TelegramCore, no change.
Add `EngineMediaResource` typealias in TelegramCore if not already present (Task 2 / Task 6 may have added it; check first).
- [ ] **Step 2a: (Only if needed) Add `EngineMediaResource` typealias**
```swift
// submodules/TelegramCore/Sources/TelegramEngine/Resources/EngineMediaResource.swift
import Postbox
public typealias EngineMediaResource = MediaResource
```
Build, commit.
- [ ] **Step 3: Edit the consumer file**
Apply mappings. Remove `import Postbox`.
- [ ] **Step 4: Drop the Bazel dep**
Edit `submodules/ICloudResources/BUILD`. Remove `"//submodules/Postbox:Postbox",` from `deps`.
- [ ] **Step 5: Static checks**
```bash
grep -R "^import Postbox" submodules/ICloudResources/Sources # expect: empty
grep "submodules/Postbox" submodules/ICloudResources/BUILD # expect: empty
```
- [ ] **Step 6: Full project build**
Run the full build. Expected: PASS. Handle failures per the Build-failure handling rules in the Background section.
- [ ] **Step 7: Commit**
```bash
git add submodules/ICloudResources/
git commit -m "$(cat <<'EOF'
ICloudResources: drop direct Postbox dependency
Switch MediaResource references to EngineMediaResource; remove the
Postbox import and Bazel dep. Behavior-preserving.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 11: Wave-1 completion verification
**Files:** No code changes.
- [ ] **Step 1: Static check across all 10 modules**
```bash
for m in ActionSheetPeerItem ChatInterfaceState ChatListSearchRecentPeersNode ChatSendMessageActionUI ContactListUI DirectMediaImageCache DrawingUI FetchManagerImpl GalleryData ICloudResources; do
echo "=== $m ==="
grep -R "^import Postbox" submodules/$m/Sources && echo "FAIL: import in $m"
grep "submodules/Postbox" submodules/$m/BUILD && echo "FAIL: dep in $m"
done
```
Expected: no `FAIL` lines printed. If any appear, return to the corresponding task and fix.
- [ ] **Step 2: Final full build**
Run the full build one more time from a clean state. Expected: PASS. (If it passed at the end of Task 10 and nothing else has changed, this should be cached and fast.)
- [ ] **Step 3: Review the commit log**
```bash
git log --oneline master..HEAD
```
Expected: a run of commits matching the pattern `TelegramCore: add …` (optional) and `<Module>: drop direct Postbox dependency` (one per module done). If any module was skipped per the fallback rule, verify the fallback ran and a replacement module completed so the total is 10.
- [ ] **Step 4: No commit**
Verification only.
---
## What's explicitly NOT in this plan
- Any edits to `TelegramCore`, `Postbox`, or the 64 modules outside the chosen 10 (except the minimum engine-wrapper / typealias additions to `TelegramCore` that the chosen modules need).
- Any new `Engine*` wrapper *structs* (only typealiases and forwarding methods are in scope this wave).
- Any generic `engine.transaction { postbox in … }` escape hatch.
- Any behavior change, performance tweak, or "while we're here" cleanup.
- Any test work — there are no tests in this project.

223
docs/superpowers/plans/2026-04-17-listview-pin-to-edge.md
View file

@ -1,223 +0,0 @@
# ListView pin-to-edge Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Implement the first-pinned-item-to-bottom-edge behavior in `ListView` by adding a `calculatePinToEdgeTopInset()` helper and wiring it into `snapToBounds` and `updateScroller`, matching the design in [docs/superpowers/specs/2026-04-17-listview-pin-to-edge-design.md](../specs/2026-04-17-listview-pin-to-edge-design.md).
**Architecture:** Heights-based virtual-top-inset adjustment. A new private helper on `ListViewImpl` computes `max(0, visibleArea - ΣheightsAboveAndIncludingPinned)`. Two call sites add this to `effectiveInsets.top` via the existing `max(…)` chain alongside `stackFromBottomInsetItemFactor`.
**Tech Stack:** Swift, ASDisplayKit, Bazel build system.
**Scope:** Single file — `submodules/Display/Source/ListView.swift`. No protocol change (`pinToEdgeWithInset` is already declared on `ListViewItem`). No consumer changes. Because no item overrides `pinToEdgeWithInset` from its default `false`, the existing app surface's behavior is unchanged after this plan lands; the feature will be exercised only by a future consumer in a separate change.
**No unit tests** exist in this project (per `CLAUDE.md`). Verification is via the full project build.
---
## Task 1: Add `calculatePinToEdgeTopInset` helper and integrate at both call sites
**Files:**
- Modify: `submodules/Display/Source/ListView.swift`
The helper, both call-site edits, and the build verification land in one commit because they are tightly coupled: committing the helper without any call site is a no-op, and committing only one of the two call sites would cause `updateScroller` and `snapToBounds` to disagree about `effectiveInsets.top`, producing scroll-position desync whenever pinning is engaged.
---
- [ ] **Step 1: Insert the `calculatePinToEdgeTopInset` helper after `calculateAdditionalTopInverseInset`**
Use the Edit tool. The helper goes immediately after `calculateAdditionalTopInverseInset`'s closing brace (line 1090) and before `areAllItemsOnScreen` (line 1092).
old_string:
```swift
private func calculateAdditionalTopInverseInset() -> CGFloat {
var additionalInverseTopInset: CGFloat = 0.0
if !self.stackFromBottomInsetItemFactor.isZero {
var remainingFactor = self.stackFromBottomInsetItemFactor
for itemNode in self.itemNodes {
if remainingFactor.isLessThanOrEqualTo(0.0) {
break
}
let itemFactor: CGFloat
if CGFloat(1.0).isLessThanOrEqualTo(remainingFactor) {
itemFactor = 1.0
} else {
itemFactor = remainingFactor
}
additionalInverseTopInset += floor(itemNode.apparentBounds.height * itemFactor)
remainingFactor -= 1.0
}
}
return additionalInverseTopInset
}
private func areAllItemsOnScreen() -> Bool {
```
new_string:
```swift
private func calculateAdditionalTopInverseInset() -> CGFloat {
var additionalInverseTopInset: CGFloat = 0.0
if !self.stackFromBottomInsetItemFactor.isZero {
var remainingFactor = self.stackFromBottomInsetItemFactor
for itemNode in self.itemNodes {
if remainingFactor.isLessThanOrEqualTo(0.0) {
break
}
let itemFactor: CGFloat
if CGFloat(1.0).isLessThanOrEqualTo(remainingFactor) {
itemFactor = 1.0
} else {
itemFactor = remainingFactor
}
additionalInverseTopInset += floor(itemNode.apparentBounds.height * itemFactor)
remainingFactor -= 1.0
}
}
return additionalInverseTopInset
}
private func calculatePinToEdgeTopInset() -> CGFloat {
var lowestPinnedIndex: Int = Int.max
for itemNode in self.itemNodes {
guard let index = itemNode.index else { continue }
if index < lowestPinnedIndex && self.items[index].pinToEdgeWithInset {
lowestPinnedIndex = index
}
}
guard lowestPinnedIndex != Int.max else { return 0.0 }
var totalAboveAndPinned: CGFloat = 0.0
var sawIndexZero = false
for itemNode in self.itemNodes {
guard let index = itemNode.index else { continue }
if index == 0 {
sawIndexZero = true
}
if index <= lowestPinnedIndex {
totalAboveAndPinned += itemNode.apparentBounds.height
}
}
guard sawIndexZero else { return 0.0 }
let visibleArea = self.visibleSize.height - self.insets.top - self.insets.bottom
return max(0.0, visibleArea - totalAboveAndPinned)
}
private func areAllItemsOnScreen() -> Bool {
```
- [ ] **Step 2: Integrate at the `snapToBounds` call site**
Use the Edit tool. The block at lines 1181-1185 in `snapToBounds` gets a new `pinToEdgeTopInset` stanza after the existing `stackFromBottomInsetItemFactor` branch. Include the following line (` ` + `if topItemFound {`) in the old_string to disambiguate from the structurally-identical block in `areAllItemsOnScreen` at line 1110.
old_string:
```swift
var effectiveInsets = self.insets
if topItemFound && !self.stackFromBottomInsetItemFactor.isZero {
let additionalInverseTopInset = self.calculateAdditionalTopInverseInset()
effectiveInsets.top = max(effectiveInsets.top, self.visibleSize.height - additionalInverseTopInset)
}
if topItemFound {
```
new_string:
```swift
var effectiveInsets = self.insets
if topItemFound && !self.stackFromBottomInsetItemFactor.isZero {
let additionalInverseTopInset = self.calculateAdditionalTopInverseInset()
effectiveInsets.top = max(effectiveInsets.top, self.visibleSize.height - additionalInverseTopInset)
}
let pinToEdgeTopInset = self.calculatePinToEdgeTopInset()
if pinToEdgeTopInset > 0.0 {
effectiveInsets.top = max(effectiveInsets.top, self.insets.top + pinToEdgeTopInset)
}
if topItemFound {
```
- [ ] **Step 3: Integrate at the `updateScroller` call site**
Use the Edit tool. The block at lines 1612-1616 in `updateScroller` is nested one extra level (12-space indent rather than 8-space), so the string alone is unique and the old_string doesn't need extra context.
old_string:
```swift
var effectiveInsets = self.insets
if topItemFound && !self.stackFromBottomInsetItemFactor.isZero {
let additionalInverseTopInset = self.calculateAdditionalTopInverseInset()
effectiveInsets.top = max(effectiveInsets.top, self.visibleSize.height - additionalInverseTopInset)
}
completeHeight = effectiveInsets.top + effectiveInsets.bottom
```
new_string:
```swift
var effectiveInsets = self.insets
if topItemFound && !self.stackFromBottomInsetItemFactor.isZero {
let additionalInverseTopInset = self.calculateAdditionalTopInverseInset()
effectiveInsets.top = max(effectiveInsets.top, self.visibleSize.height - additionalInverseTopInset)
}
let pinToEdgeTopInset = self.calculatePinToEdgeTopInset()
if pinToEdgeTopInset > 0.0 {
effectiveInsets.top = max(effectiveInsets.top, self.insets.top + pinToEdgeTopInset)
}
completeHeight = effectiveInsets.top + effectiveInsets.bottom
```
- [ ] **Step 4: Run the full project build**
Use the Bash tool. The build takes several minutes; run it in the foreground so the agent waits for completion and surfaces failures immediately. The `source ~/.zshrc` prefix picks up `TELEGRAM_CODESIGNING_GIT_PASSWORD` per the build-environment quirk documented in `CLAUDE.md`.
```
source ~/.zshrc 2>/dev/null; PATH=/opt/homebrew/opt/ruby/bin:`gem environment gemdir`/bin:$PATH python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber 1 --configuration debug_sim_arm64
```
Expected: successful build. No warnings or errors touching `ListView.swift`.
If the build fails:
- Swift syntax error → re-read `ListView.swift` around the edited regions; compare against the plan's old_string/new_string; fix and re-run.
- "`pinToEdgeWithInset` has no member" → the protocol property wasn't found; verify `submodules/Display/Source/ListViewItem.swift:80` still declares `var pinToEdgeWithInset: Bool { get }` and the default implementation at `ListViewItem.swift:102` is intact. If intact but the error persists, check that the `items` array's element type is `ListViewItem` (it is — see `public final var items: [ListViewItem]` in `ListView.swift`).
- Any other failure in unrelated files → not caused by this plan; investigate separately.
- [ ] **Step 5: Commit**
```bash
git add submodules/Display/Source/ListView.swift
git commit -m "$(cat <<'EOF'
Display/ListView: pin first pinToEdgeWithInset item to bottom edge
Adds calculatePinToEdgeTopInset() and wires it into snapToBounds and
updateScroller. When the smallest-index item with pinToEdgeWithInset=true
plus all items above it have a combined apparentBounds height less than
the available scrolling area, the helper returns a positive top-inset
contribution that pushes the pinned item's maxY to visibleSize.height -
insets.bottom. Once items above reach the available area, the
contribution is zero and scrolling is fully ordinary.
Spec: docs/superpowers/specs/2026-04-17-listview-pin-to-edge-design.md
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
Verify with `git status` that the tree is clean after the commit.
---
## Rationale for task granularity
This plan has a single task. I considered splitting "add helper" from "apply at two call sites" into two commits:
- **For splitting:** one commit per "unit of change" is more bisectable.
- **Against splitting:** the helper alone is unused (runtime no-op, and Swift does not warn on unused private methods). Applying at one call site without the other would produce a live bug — `snapToBounds` and `updateScroller` would disagree whenever pinning engages, and `updateScroller` is what sets `scroller.contentSize`/`contentOffset`. Three commits land an internally-consistent state only at the third commit.
Bundling all edits preserves bisectability at the feature-level boundary (the commit either introduces pin-to-edge support or it doesn't) and keeps the repo free of intermediate broken states.

880
docs/superpowers/plans/2026-04-17-mediaresource-to-enginemediaresource-wave-2.md
View file

@ -1,880 +0,0 @@
# MediaResource → EngineMediaResource Refactor (Wave 2) — Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Drive raw `MediaResource` (Postbox protocol) out of the `TelegramEngine` public facade by changing facade-function signatures in-place to take/return `EngineMediaResource`, bridging to the existing `_internal_*` Postbox-facing implementations via wrap/unwrap helpers. In the same commit as each facade change, update every call site. Follow up with a first small batch of consumer type-reference migrations.
**Architecture:** `TelegramEngine` facade methods live alongside `_internal_*` Postbox-using implementations in `submodules/TelegramCore/Sources/TelegramEngine/<Area>/`. Today the facade methods already bridge (storing an `Account` and delegating), but their public signatures still expose raw `MediaResource`. The fix: change facade signatures to `EngineMediaResource` (including the `mapResourceToAvatarSizes` closure types) and add the two-line wrap/unwrap bridging. `_internal_*` functions stay on raw `MediaResource` — they are the Postbox-facing layer and must remain so. Consumer call sites swap `MediaResource` → `EngineMediaResource` (usually via `EngineMediaResource(raw)` wrap or `engineResource._asResource()` unwrap at a nearby boundary).
**Tech Stack:** Swift, Bazel, Postbox (opaque storage), TelegramCore (public facade), SSignalKit.
**Design constraint (IMPORTANT):** `TelegramCore` is shared with the Telegram-Mac codebase and must **not** import UIKit/Display. Any UIKit-requiring logic (image scaling, `UIImage`, `generateScaledImage`, etc.) stays in consumer-side submodules. Engine API additions must not pull in UIKit.
**Why not overloads:** An earlier iteration of this plan added opt-in `EngineMediaResource` overloads and kept the raw overloads. That was rejected: duplicate signatures fragment the public API and leave raw-`MediaResource` leaks forever. The correct pattern is to change the single facade function in-place so it takes engine types and bridges inside, forcing callers to migrate in the same commit.
---
## Background the executor needs
### The full build command
Run from the repo root (`/Users/ali/build/telegram/telegram-ios`):
```bash
source ~/.zshrc 2>/dev/null; \
PATH=/opt/homebrew/opt/ruby/bin:`gem environment gemdir`/bin:$PATH \
python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development \
--gitCodesigningUseCurrent \
--buildNumber 1 \
--configuration debug_sim_arm64
```
The build is the only verification (no unit tests per `CLAUDE.md`). Every task ends with a full build that must go green before the next task starts.
### What `EngineMediaResource` gives you today (bridge primitives)
Defined in [TelegramEngineResources.swift](../../../submodules/TelegramCore/Sources/TelegramEngine/Resources/TelegramEngineResources.swift):
```swift
public final class EngineMediaResource: Equatable {
public init(_ resource: MediaResource)
public func _asResource() -> MediaResource
public var id: Id
public struct Id: Equatable, Hashable {
public init(_ id: MediaResourceId)
public init(_ stringRepresentation: String)
}
public final class ResourceData {
public let path: String; public let availableSize: Int64; public let isComplete: Bool
}
public enum FetchStatus: Equatable { /* Remote/Local/Fetching/Paused */ }
}
public extension EngineMediaResource.ResourceData {
convenience init(_ data: MediaResourceData)
}
```
### The bridging pattern
For each facade function whose public signature contains `MediaResource`:
**Before** (raw-protocol leak):
```swift
public func uploadedPeerPhoto(resource: MediaResource) -> Signal<UploadedPeerPhotoData, NoError> {
return _internal_uploadedPeerPhoto(postbox: self.account.postbox, network: self.account.network, resource: resource)
}
```
**After** (engine-typed facade, internal bridge):
```swift
public func uploadedPeerPhoto(resource: EngineMediaResource) -> Signal<UploadedPeerPhotoData, NoError> {
return _internal_uploadedPeerPhoto(postbox: self.account.postbox, network: self.account.network, resource: resource._asResource())
}
```
For closures that receive a `MediaResource`:
**Before:**
```swift
public func updatePeerPhoto(..., mapResourceToAvatarSizes: @escaping (MediaResource, [TelegramMediaImageRepresentation]) -> Signal<[Int: Data], NoError>) -> ... {
return _internal_updatePeerPhoto(..., mapResourceToAvatarSizes: mapResourceToAvatarSizes)
}
```
**After:**
```swift
public func updatePeerPhoto(..., mapResourceToAvatarSizes: @escaping (EngineMediaResource, [TelegramMediaImageRepresentation]) -> Signal<[Int: Data], NoError>) -> ... {
return _internal_updatePeerPhoto(..., mapResourceToAvatarSizes: { rawResource, representations in
mapResourceToAvatarSizes(EngineMediaResource(rawResource), representations)
})
}
```
`_internal_*` functions are **not** changed — they stay on raw `MediaResource` as the Postbox-facing layer.
### Call-site migration pattern
At each call site, the change is mechanical:
- `engine.peers.uploadedPeerPhoto(resource: someRawResource)` → `engine.peers.uploadedPeerPhoto(resource: EngineMediaResource(someRawResource))`.
- `engine.peers.updatePeerPhoto(..., mapResourceToAvatarSizes: { resource, representations in ... resource ... })` — the closure's `resource` is now `EngineMediaResource`. Any expression inside the closure that previously treated `resource` as raw protocol (e.g. `postbox.mediaBox.resourceData(resource)`) must use `resource._asResource()`.
Where the consumer was carrying a `MediaResource?` property / local purely as a pipe into one of these APIs, migrate the property itself to `EngineMediaResource?` so no unwrap/wrap churn is needed.
### Static-check commands
```bash
grep -R "^import Postbox" submodules/<M>/Sources # expect: empty (only when a module is being fully de-Postboxed)
grep "submodules/Postbox" submodules/<M>/BUILD # expect: empty (same condition)
```
### Commit convention
- One commit per engine API family: `TelegramCore: migrate <function(s)> to EngineMediaResource` — bundles facade-signature change **and** all call sites updated in the same commit. The repo must build on every commit.
- Consumer-only type-ref commits: `<ModuleName>: migrate MediaResource property to EngineMediaResource` or `<ModuleName>: drop direct Postbox dependency`.
- Always use HEREDOC bodies. No `--amend`.
### What is explicitly out of scope
- Classes that **conform to `TelegramMediaResource`** (must implement `isEqual(to: MediaResource)`): remain `import Postbox`. Enumerated:
- `submodules/ICloudResources/Sources/ICloudResources.swift` — `ICloudFileResource`
- `submodules/InstantPageUI/Sources/InstantPageExternalMediaResource.swift` — `InstantPageExternalMediaResource`
- `submodules/LocalMediaResources/Sources/LocalMediaResources.swift` — `VideoLibraryMediaResource`
- `submodules/TelegramUniversalVideoContent/Sources/YoutubeEmbedImplementation.swift` — `YoutubeEmbedStoryboardMediaResource`
- TelegramCore-internal `MediaResource` usage (SyncCore, Fetch, `_internal_*` functions, etc.) — Postbox-facing layer.
- Modules already abandoned in wave 1 for non-MediaResource reasons (`FetchManagerImpl` / `ICloudResources` have other umbrella-type blockers).
- The heavy-leak modules in the "Future waves" table at the bottom (`PassportUI`, `TelegramUI`, etc.).
- Importing UIKit/Display into TelegramCore under any circumstance.
---
## Task 0: Baseline verification
**Files:** No code changes.
- [ ] **Step 1: Confirm tree state**
```bash
git status
git log --oneline -5
```
Expected: working tree clean apart from pre-existing untracked (`build-system/tulsi/`, `submodules/TgVoip/`, `third-party/libx264/`) and submodule-content drift on `build-system/bazel-rules/sourcekit-bazel-bsp`. HEAD on `master`.
- [ ] **Step 2: Baseline build**
Run the full build command above. Expected: PASS.
If it fails, stop — a non-green baseline is out of scope.
- [ ] **Step 3: No commit.**
---
## Task 1: Record the new rules in CLAUDE.md
**Files:**
- Modify: `CLAUDE.md`
- [ ] **Step 1: Add the "TelegramCore no UIKit" rule**
In `CLAUDE.md`, inside the `## Postbox → TelegramEngine refactor (in progress)` section, under `### Rules that apply to every wave`, append a new numbered rule after the existing rule 6:
```markdown
7. **TelegramCore never imports UIKit/Display.** `TelegramCore` is shared with the Telegram-Mac codebase; its Bazel `deps` and source files must not reference UIKit, Display, or any Apple-UI framework. UIKit-needing helpers (image scaling, rendering, etc.) stay in consumer-side submodules.
```
- [ ] **Step 2: Add the MediaResource → EngineMediaResource migration pattern**
After the `### Engine typealias cheat sheet (existing aliases)` block (which ends with the `MediaResource` / `TelegramMediaResource` note), insert a new section:
```markdown
### MediaResource → EngineMediaResource consumer migration
`EngineMediaResource` is a `final class` in `TelegramCore` wrapping a `MediaResource` value. Unlike the typealiases above it is **not** interchangeable with the protocol, but it does provide wrap/unwrap helpers:
- `EngineMediaResource(rawResource)` — wrap a raw `MediaResource`.
- `engineResource._asResource()` — unwrap to the raw `MediaResource`.
- `EngineMediaResource.ResourceData(rawResourceData)` — wrap `MediaResourceData`.
- `EngineMediaResource.Id(rawMediaResourceId)` — wrap `MediaResourceId`.
**Pattern for facade functions:** when a `TelegramEngine.<Area>` method leaks raw `MediaResource` in its public signature, **change the facade signature in place** to `EngineMediaResource` (and change any closure parameter types the same way). Bridge inside the facade body by calling the existing `_internal_*` function with `engineResource._asResource()` / wrapping raw inputs from inner closures with `EngineMediaResource(rawResource)`. Update all call sites in the same commit. The `_internal_*` function stays on raw `MediaResource` — it is the Postbox-facing layer.
Do **not** add opt-in `EngineMediaResource` overloads alongside raw-`MediaResource` overloads. Duplicate signatures fragment the public API and leave the leak in place forever.
For consumer modules, prefer `EngineMediaResource` as the type in properties, locals, generic arguments and function parameters when the usage is a pure type reference. Do **not** try to use `EngineMediaResource` where a class must conform to `TelegramMediaResource` (Postbox protocol) or override `isEqual(to: MediaResource)` — those remain `import Postbox`.
```
- [ ] **Step 3: Full build (sanity — docs only)**
Run the full build. Expected: PASS.
- [ ] **Step 4: Commit**
```bash
git add CLAUDE.md
git commit -m "$(cat <<'EOF'
CLAUDE.md: record TelegramCore-no-UIKit rule and EngineMediaResource migration pattern
Wave-2 preparation. Codifies that TelegramCore is shared with
Telegram-Mac and must stay UIKit-free, and documents the
modify-in-place / bridge-inside pattern for migrating
MediaResource-leaking facade functions to EngineMediaResource.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 2: Migrate `TelegramEngine.Peers` photo APIs to `EngineMediaResource`
**Files:**
- Modify: `submodules/TelegramCore/Sources/TelegramEngine/Peers/TelegramEnginePeers.swift`
- Modify: all call sites (13 + 11 + 7, with heavy overlap — see Step 2 grep).
**Functions migrated in this task:**
- `uploadedPeerPhoto(resource:)` (line 704) — `MediaResource` → `EngineMediaResource`
- `uploadedPeerVideo(resource:)` (line 708) — `MediaResource` → `EngineMediaResource`
- `updatePeerPhoto(..., mapResourceToAvatarSizes:)` (line 712) — closure parameter `MediaResource` → `EngineMediaResource`
- [ ] **Step 1: Read the current signatures**
Read lines 704–720 of `submodules/TelegramCore/Sources/TelegramEngine/Peers/TelegramEnginePeers.swift`. Confirm the three functions match the pattern `return _internal_<name>(postbox: self.account.postbox, ..., resource: resource)` or equivalent.
- [ ] **Step 2: Enumerate call sites**
```bash
grep -rnE "\\.(uploadedPeerPhoto|uploadedPeerVideo|updatePeerPhoto)\(" submodules/ \
| grep -v "submodules/TelegramCore"
```
Capture every hit — file path, line number, approximate surrounding context (what resource expression is passed in / what the closure body does). The distribution as of planning:
- `uploadedPeerPhoto`: 11 call sites (spread across TelegramUI, TelegramCallsUI, AuthorizationUI, etc.)
- `uploadedPeerVideo`: 7
- `updatePeerPhoto`: 13
Many call sites chain these (e.g. `updatePeerPhoto(photo: engine.peers.uploadedPeerPhoto(resource: ...))`) so a single file often touches two or three of them in one call.
- [ ] **Step 3: Change the facade signatures + bridge**
In `TelegramEnginePeers.swift`, change the three functions to:
```swift
public func uploadedPeerPhoto(resource: EngineMediaResource) -> Signal<UploadedPeerPhotoData, NoError> {
return _internal_uploadedPeerPhoto(postbox: self.account.postbox, network: self.account.network, resource: resource._asResource())
}
public func uploadedPeerVideo(resource: EngineMediaResource) -> Signal<UploadedPeerPhotoData, NoError> {
return _internal_uploadedPeerVideo(postbox: self.account.postbox, network: self.account.network, messageMediaPreuploadManager: self.account.messageMediaPreuploadManager, resource: resource._asResource())
}
public func updatePeerPhoto(peerId: PeerId, photo: Signal<UploadedPeerPhotoData, NoError>?, video: Signal<UploadedPeerPhotoData?, NoError>? = nil, videoStartTimestamp: Double? = nil, markup: UploadPeerPhotoMarkup? = nil, mapResourceToAvatarSizes: @escaping (EngineMediaResource, [TelegramMediaImageRepresentation]) -> Signal<[Int: Data], NoError>) -> Signal<UpdatePeerPhotoStatus, UploadPeerPhotoError> {
return _internal_updatePeerPhoto(postbox: self.account.postbox, network: self.account.network, stateManager: self.account.stateManager, accountPeerId: self.account.peerId, peerId: peerId, photo: photo, video: video, videoStartTimestamp: videoStartTimestamp, markup: markup, mapResourceToAvatarSizes: { rawResource, representations in
return mapResourceToAvatarSizes(EngineMediaResource(rawResource), representations)
})
}
```
**Before editing, re-read the existing bodies** — the exact arg names passed into `_internal_updatePeerPhoto` etc. must match what's already there (the skeletons above reproduce what's in the file at planning time, but the executor should preserve every argument the current implementation passes). Only the outer signature and the closure-wrapping change.
- [ ] **Step 4: Update every call site** (same commit)
For each hit from Step 2, rewrite the call site per the patterns:
**Pattern A — passing a raw resource to `uploadedPeerPhoto` / `uploadedPeerVideo`:**
```swift
// Before:
engine.peers.uploadedPeerPhoto(resource: someRawResource)
// After:
engine.peers.uploadedPeerPhoto(resource: EngineMediaResource(someRawResource))
```
**Pattern B — the `mapResourceToAvatarSizes` closure of `updatePeerPhoto`:**
```swift
// Before:
mapResourceToAvatarSizes: { resource, representations in
return mapResourceToAvatarSizes(postbox: postbox, resource: resource, representations: representations)
}
// After (if the helper is still raw-MediaResource-facing at this point):
mapResourceToAvatarSizes: { resource, representations in
return mapResourceToAvatarSizes(postbox: postbox, resource: resource._asResource(), representations: representations)
}
```
Task 6 will change `mapResourceToAvatarSizes` itself to accept `EngineMediaResource` and drop the `_asResource()` call. Until Task 6 lands, keep the `_asResource()` here. This keeps the build green between tasks.
**Pattern C — the consumer was already carrying the resource as a `MediaResource?` local purely as a pipe:**
If a nearby local/property typed `MediaResource?` only exists to feed `uploadedPeerPhoto(resource:)` or similar, change the local's type to `EngineMediaResource?` at the same time. This avoids wrap/unwrap churn at the call site.
- [ ] **Step 5: Full build**
Run the full build. Expected: PASS.
If it fails, the first error locates the broken call site. Apply Pattern A / B / C at that site and rebuild. If a file imports Postbox only for `MediaResource` and now has no other Postbox identifier, you may optionally remove `import Postbox` in the same commit — but that is not required here; it is a separate goal.
- [ ] **Step 6: Commit**
```bash
git add submodules/TelegramCore/Sources/TelegramEngine/Peers/TelegramEnginePeers.swift submodules/
git commit -m "$(cat <<'EOF'
TelegramCore: migrate peer-photo facade to EngineMediaResource
Change TelegramEngine.Peers.uploadedPeerPhoto / uploadedPeerVideo /
updatePeerPhoto so their public signatures take EngineMediaResource
instead of raw MediaResource (and the mapResourceToAvatarSizes closure
receives EngineMediaResource). The facade bridges to the existing
_internal_* Postbox-facing implementations via _asResource() /
EngineMediaResource(_:). All call sites updated in this commit.
Part of the MediaResource -> EngineMediaResource migration (wave 2).
No behavior change.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 3: Migrate `TelegramEngine.AccountData.updateAccountPhoto` and `updateFallbackPhoto`
**Files:**
- Modify: `submodules/TelegramCore/Sources/TelegramEngine/AccountData/TelegramEngineAccountData.swift`
- Modify: all call sites (5 + 4).
- [ ] **Step 1: Read the current signatures**
Read lines 55–90 of `submodules/TelegramCore/Sources/TelegramEngine/AccountData/TelegramEngineAccountData.swift`. Confirm both functions match the expected pattern.
- [ ] **Step 2: Enumerate call sites**
```bash
grep -rnE "\\.(updateAccountPhoto|updateFallbackPhoto)\(" submodules/ \
| grep -v "submodules/TelegramCore"
```
- [ ] **Step 3: Change the facade signatures + bridge**
Change both functions in place:
```swift
public func updateAccountPhoto(resource: EngineMediaResource?, videoResource: EngineMediaResource?, videoStartTimestamp: Double?, markup: UploadPeerPhotoMarkup?, mapResourceToAvatarSizes: @escaping (EngineMediaResource, [TelegramMediaImageRepresentation]) -> Signal<[Int: Data], NoError>) -> Signal<UpdatePeerPhotoStatus, UploadPeerPhotoError> {
return _internal_updateAccountPhoto(account: self.account, resource: resource?._asResource(), videoResource: videoResource?._asResource(), videoStartTimestamp: videoStartTimestamp, markup: markup, mapResourceToAvatarSizes: { rawResource, representations in
return mapResourceToAvatarSizes(EngineMediaResource(rawResource), representations)
})
}
public func updateFallbackPhoto(resource: EngineMediaResource?, videoResource: EngineMediaResource?, videoStartTimestamp: Double?, markup: UploadPeerPhotoMarkup?, mapResourceToAvatarSizes: @escaping (EngineMediaResource, [TelegramMediaImageRepresentation]) -> Signal<[Int: Data], NoError>) -> Signal<UpdatePeerPhotoStatus, UploadPeerPhotoError> {
return _internal_updateFallbackPhoto(account: self.account, resource: resource?._asResource(), videoResource: videoResource?._asResource(), videoStartTimestamp: videoStartTimestamp, markup: markup, mapResourceToAvatarSizes: { rawResource, representations in
return mapResourceToAvatarSizes(EngineMediaResource(rawResource), representations)
})
}
```
**Before editing, verify the exact argument names passed to `_internal_updateAccountPhoto` / `_internal_updateFallbackPhoto`** in the current file. Copy those argument spellings verbatim (only the outer signature and inner closure wrapping change).
- [ ] **Step 4: Update every call site** (same commit)
Apply Pattern A/B/C from Task 2 to every hit. Wrap `EngineMediaResource(...)` around raw-resource args; add `._asResource()` inside any `mapResourceToAvatarSizes:` closure body where it hands the value onward to a still-raw helper (removed in Task 6).
- [ ] **Step 5: Full build**
Run the full build. Expected: PASS.
- [ ] **Step 6: Commit**
```bash
git add submodules/TelegramCore/Sources/TelegramEngine/AccountData/TelegramEngineAccountData.swift submodules/
git commit -m "$(cat <<'EOF'
TelegramCore: migrate account-photo facade to EngineMediaResource
Change TelegramEngine.AccountData.updateAccountPhoto and
updateFallbackPhoto so their public signatures take EngineMediaResource
(and the mapResourceToAvatarSizes closure receives
EngineMediaResource). Bridges to _internal_* functions via
_asResource()/EngineMediaResource(_:). All call sites updated in this
commit.
Part of the MediaResource -> EngineMediaResource migration (wave 2).
No behavior change.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 4: Migrate `TelegramEngine.Contacts.updateContactPhoto`
**Files:**
- Modify: `submodules/TelegramCore/Sources/TelegramEngine/Contacts/TelegramEngineContacts.swift`
- Modify: all call sites (8).
- [ ] **Step 1: Read the current signature**
Read around line 33 of `submodules/TelegramCore/Sources/TelegramEngine/Contacts/TelegramEngineContacts.swift`.
- [ ] **Step 2: Enumerate call sites**
```bash
grep -rn "\.updateContactPhoto(" submodules/ | grep -v "submodules/TelegramCore"
```
- [ ] **Step 3: Change the facade signature + bridge**
```swift
public func updateContactPhoto(peerId: PeerId, resource: EngineMediaResource?, videoResource: EngineMediaResource?, videoStartTimestamp: Double?, markup: UploadPeerPhotoMarkup?, mode: SetCustomPeerPhotoMode, mapResourceToAvatarSizes: @escaping (EngineMediaResource, [TelegramMediaImageRepresentation]) -> Signal<[Int: Data], NoError>) -> Signal<UpdatePeerPhotoStatus, UploadPeerPhotoError> {
return _internal_updateContactPhoto(account: self.account, peerId: peerId, resource: resource?._asResource(), videoResource: videoResource?._asResource(), videoStartTimestamp: videoStartTimestamp, markup: markup, mode: mode, mapResourceToAvatarSizes: { rawResource, representations in
return mapResourceToAvatarSizes(EngineMediaResource(rawResource), representations)
})
}
```
Verify the `_internal_updateContactPhoto` call spelling against the existing file before committing.
- [ ] **Step 4: Update every call site** (same commit)
Pattern A/B/C as in Task 2.
- [ ] **Step 5: Full build**
Run the full build. Expected: PASS.
- [ ] **Step 6: Commit**
```bash
git add submodules/TelegramCore/Sources/TelegramEngine/Contacts/TelegramEngineContacts.swift submodules/
git commit -m "$(cat <<'EOF'
TelegramCore: migrate updateContactPhoto facade to EngineMediaResource
Change TelegramEngine.Contacts.updateContactPhoto so its public
signature takes EngineMediaResource parameters and the
mapResourceToAvatarSizes closure receives EngineMediaResource. Bridges
to _internal_updateContactPhoto via _asResource()/EngineMediaResource(_:).
All call sites updated in this commit.
Part of the MediaResource -> EngineMediaResource migration (wave 2).
No behavior change.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 5: Migrate `TelegramEngine.Auth.uploadedPeerVideo`
**Files:**
- Modify: `submodules/TelegramCore/Sources/TelegramEngine/Auth/TelegramEngineAuth.swift`
- Modify: call sites that route through `TelegramEngine.Auth.uploadedPeerVideo` (separate from `TelegramEngine.Peers.uploadedPeerVideo`).
- [ ] **Step 1: Read the current signature**
Read around line 51 of `submodules/TelegramCore/Sources/TelegramEngine/Auth/TelegramEngineAuth.swift`.
- [ ] **Step 2: Enumerate call sites**
```bash
grep -rn "engine\.auth\.uploadedPeerVideo\|\.auth\.uploadedPeerVideo" submodules/ | grep -v "submodules/TelegramCore"
```
The call site count is small (the sign-up flow). If zero, skip Step 4.
- [ ] **Step 3: Change the facade signature + bridge**
```swift
public func uploadedPeerVideo(resource: EngineMediaResource) -> Signal<UploadedPeerPhotoData, NoError> {
return _internal_uploadedPeerVideo(postbox: self.account.postbox, network: self.account.network, messageMediaPreuploadManager: self.account.messageMediaPreuploadManager, resource: resource._asResource())
}
```
Preserve the exact argument spellings from the existing function body.
- [ ] **Step 4: Update call sites** (same commit)
Pattern A.
- [ ] **Step 5: Full build**
Run the full build. Expected: PASS.
- [ ] **Step 6: Commit**
```bash
git add submodules/TelegramCore/Sources/TelegramEngine/Auth/TelegramEngineAuth.swift submodules/
git commit -m "$(cat <<'EOF'
TelegramCore: migrate Auth.uploadedPeerVideo facade to EngineMediaResource
Signature change + call sites.
Part of the MediaResource -> EngineMediaResource migration (wave 2).
No behavior change.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 6: Migrate `mapResourceToAvatarSizes` utility and drop `import Postbox` from `MapResourceToAvatarSizes`
**Files:**
- Modify: `submodules/MapResourceToAvatarSizes/Sources/MapResourceToAvatarSizes.swift`
- Modify: `submodules/MapResourceToAvatarSizes/BUILD`
- Modify: all 27 call sites of the old `mapResourceToAvatarSizes(postbox:resource:representations:)`.
**Preconditions:** Tasks 2–5 have landed, so every `mapResourceToAvatarSizes:` closure at call sites now receives an `EngineMediaResource` (because the facade closures were retyped). At this point the inner `mapResourceToAvatarSizes(postbox: …, resource: …._asResource(), …)` unwrap becomes avoidable.
- [ ] **Step 1: Read the current file**
```
submodules/MapResourceToAvatarSizes/Sources/MapResourceToAvatarSizes.swift
```
Confirm the function body uses `postbox.mediaBox.resourceData(resource)` and requires `UIImage` / `generateScaledImage` / `jpegData(compressionQuality:)`.
- [ ] **Step 2: Enumerate call sites**
```bash
grep -rn "mapResourceToAvatarSizes(postbox:" submodules/ | grep -v "submodules/MapResourceToAvatarSizes"
```
Expected: 27 call sites, concentrated in `submodules/TelegramUI/...PeerInfoScreenAvatarSetup.swift` (19), `TelegramCallsUI/...VideoChatScreenParticipantContextMenu.swift` (5), and three other TelegramUI files (1 each).
- [ ] **Step 3: Rewrite the function to use `EngineMediaResource` + `TelegramEngine.Resources.data`**
Replace the body of `submodules/MapResourceToAvatarSizes/Sources/MapResourceToAvatarSizes.swift` with:
```swift
import Foundation
import UIKit
import SwiftSignalKit
import TelegramCore
import Display
public func mapResourceToAvatarSizes(engine: TelegramEngine, resource: EngineMediaResource, representations: [TelegramMediaImageRepresentation]) -> Signal<[Int: Data], NoError> {
return engine.resources.data(id: resource.id)
|> take(1)
|> map { data -> [Int: Data] in
guard data.isComplete, let image = UIImage(contentsOfFile: data.path) else {
return [:]
}
var result: [Int: Data] = [:]
for i in 0 ..< representations.count {
let size: CGSize
if representations[i].dimensions.width == 80 {
size = CGSize(width: 160.0, height: 160.0)
} else {
size = representations[i].dimensions.cgSize
}
if let scaledImage = generateScaledImage(image: image, size: size, scale: 1.0), let scaledData = scaledImage.jpegData(compressionQuality: 0.8) {
result[i] = scaledData
}
}
return result
}
}
```
Notes:
- Signature: `(engine: TelegramEngine, resource: EngineMediaResource, representations: [TelegramMediaImageRepresentation]) -> Signal<[Int: Data], NoError>`.
- `import Postbox` is gone; replaced usage with `engine.resources.data(id:)` which returns `Signal<EngineMediaResource.ResourceData, NoError>`.
- `data.complete` → `data.isComplete` (field rename on the engine wrapper).
- [ ] **Step 4: Drop the Bazel dep**
Edit `submodules/MapResourceToAvatarSizes/BUILD` and remove `"//submodules/Postbox:Postbox",` from `deps`. Leave the rest untouched.
- [ ] **Step 5: Update every call site** (same commit)
At each of the 27 sites, two changes:
**Pattern D — the call site already lives inside a `mapResourceToAvatarSizes:` closure on a facade function (post-Task-2/3/4, the closure's `resource` parameter is now `EngineMediaResource`):**
```swift
// Before (from an intermediate state between tasks):
mapResourceToAvatarSizes: { resource, representations in
return mapResourceToAvatarSizes(postbox: postbox, resource: resource._asResource(), representations: representations)
}
// After:
mapResourceToAvatarSizes: { resource, representations in
return mapResourceToAvatarSizes(engine: engine, resource: resource, representations: representations)
}
```
The `engine` value is always reachable at the call site — it's either a stored reference used right above the closure or `context.engine` / `accountContext.engine`. Grep shows every current call site has a `postbox = context.account.postbox` (or similar) just above, so `context.engine` / the adjacent engine reference is in scope.
**Pattern E — direct (non-closure) call with a raw `MediaResource` in scope:**
Rare in the current code, but if you find one, wrap with `EngineMediaResource(rawResource)` at the call.
- [ ] **Step 6: Static checks**
```bash
grep -R "^import Postbox" submodules/MapResourceToAvatarSizes/Sources # expect: empty
grep "submodules/Postbox" submodules/MapResourceToAvatarSizes/BUILD # expect: empty
```
- [ ] **Step 7: Full build**
Run the full build. Expected: PASS.
Likely failure modes:
- A call site's surrounding scope doesn't have an `engine` in context. Fix: use `<nearby-accountContext>.engine` or promote `engine` to a nearby `let`.
- A consumer file passed a non-`EngineMediaResource` into the closure because it wasn't updated by Task 2/3/4. Fix forward (update it now) and record the miss.
- [ ] **Step 8: Commit**
```bash
git add submodules/MapResourceToAvatarSizes/ submodules/TelegramUI/ submodules/TelegramCallsUI/
git commit -m "$(cat <<'EOF'
MapResourceToAvatarSizes: migrate to EngineMediaResource and drop Postbox
Change the signature of mapResourceToAvatarSizes from
(postbox: Postbox, resource: MediaResource, ...) to
(engine: TelegramEngine, resource: EngineMediaResource, ...), using
engine.resources.data(id:) internally. All 27 call sites updated in
this commit. `import Postbox` and the Bazel dep are removed.
Behavior-preserving.
Part of the MediaResource -> EngineMediaResource migration (wave 2).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 7: Migrate `AuthorizationUI` signal type
**Files:**
- Modify: `submodules/AuthorizationUI/Sources/AuthorizationSequenceController.swift`
**Starting inventory:** exactly one reference — `Signal<TelegramMediaResource?, NoError>` at line 1162. AuthorizationUI has six files importing Postbox overall; dropping `import Postbox` from the module as a whole is **not** in scope for this task.
- [ ] **Step 1: Read line 1162 ± 20**
Understand:
- What value is put into the signal? Likely some TelegramMediaResource subclass (e.g. `LocalFileMediaResource`).
- Who consumes the signal downstream? After Tasks 2–5, any facade that ultimately receives this signal's value (via `updateAccountPhoto`, `uploadedPeerVideo`, etc.) expects `EngineMediaResource`.
- [ ] **Step 2: Change the signal type**
```swift
// Before:
avatarVideo = Signal<TelegramMediaResource?, NoError> { subscriber in
// ... produces a TelegramMediaResource ...
subscriber.putNext(someResource)
}
// After:
avatarVideo = Signal<EngineMediaResource?, NoError> { subscriber in
// ... produces a TelegramMediaResource ...
subscriber.putNext(someResource.flatMap { EngineMediaResource($0) }) // or wrap the non-optional path
}
```
The exact wrapping site depends on where the raw resource flows in. The grep + read from Step 1 tells you.
Downstream, any call site that consumed the raw resource and handed it to an engine facade now has an `EngineMediaResource?` which it can pass directly (post-Tasks 2–5).
- [ ] **Step 3: Full build**
Run the full build. Expected: PASS.
If the downstream expected a `TelegramMediaResource?` (e.g. for direct Postbox access that wasn't part of Tasks 2–5), revert this task as `Abandoned — downstream expects raw protocol` with a recorded reason.
- [ ] **Step 4: Commit**
```bash
git add submodules/AuthorizationUI/Sources/AuthorizationSequenceController.swift
git commit -m "$(cat <<'EOF'
AuthorizationUI: migrate avatar-video signal type to EngineMediaResource
Single type-reference swap. Downstream engine facades already accept
EngineMediaResource after the Phase-1 migrations. Behavior-preserving.
Part of the MediaResource -> EngineMediaResource migration (wave 2).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 8: Migrate `SaveToCameraRoll` property type — **ABANDONED**
**Status:** Abandoned in wave 2. No code changes from this task.
**Reason:** The planning-time grep that produced the "one reference" inventory only matched `MediaResource`/`TelegramMediaResource` tokens, not the broader set of Postbox usages. Re-inventorying the module at execution time (`grep -nE "\b(postbox|mediaBox|MediaResource)\b|^import Postbox" submodules/SaveToCameraRoll/Sources/SaveToCameraRoll.swift`) shows three public functions with `postbox: Postbox` in their signatures (`fetchMediaData`, `saveToCameraRoll`, `copyToPasteboard`) plus multiple `postbox.mediaBox.*` calls in their bodies. Per spec rule 2, `Postbox` is an umbrella type that cannot be typealiased, so those public-API signatures cannot be de-Postboxed without editing every caller; and the internal `postbox.mediaBox.*` calls require engine-side wrappers (closer to Task 6's shape) rather than a simple type swap. Scope is a full module-migration wave, not a single type swap — parked for a future wave.
**Original task body (retained for audit trail, do not implement):**
**Files:**
- Modify: `submodules/SaveToCameraRoll/Sources/SaveToCameraRoll.swift`
- Possibly modify: `submodules/SaveToCameraRoll/BUILD`
**Starting inventory:** one reference — `var resource: MediaResource?` at line 19.
- [ ] **Step 1: Read + full grep**
```bash
grep -nE "\b(MediaResource|TelegramMediaResource|postbox|mediaBox|transaction|PostboxView|combinedView)\b|^import Postbox" submodules/SaveToCameraRoll/Sources/SaveToCameraRoll.swift
```
Capture every hit.
- [ ] **Step 2: Abandon-check**
If the grep shows Postbox usages other than the single `MediaResource?` property and an `import Postbox` line, abandon this task with a recorded reason. Do not substitute.
If it shows only the property + import, proceed.
- [ ] **Step 3: Swap the property type + boundary wrap/unwrap**
Change `var resource: MediaResource?` to `var resource: EngineMediaResource?`. At each assignment/use:
- Assignment from a raw resource: `self.resource = EngineMediaResource(rawResource)`; `self.resource = nil` unchanged.
- Read that hands to mediaBox/postbox (if any remains): `self.resource?._asResource()`.
- [ ] **Step 4: Drop `import Postbox` if now unused**
If Step 1 showed `import Postbox` as the only remaining Postbox reference:
- Remove the `import Postbox` line.
- Remove `"//submodules/Postbox:Postbox",` from `submodules/SaveToCameraRoll/BUILD`.
Static checks:
```bash
grep -R "^import Postbox" submodules/SaveToCameraRoll/Sources # expect: empty
grep "submodules/Postbox" submodules/SaveToCameraRoll/BUILD # expect: empty
```
Else skip this step.
- [ ] **Step 5: Full build**
Run the full build. Expected: PASS.
- [ ] **Step 6: Commit**
If the import was removed:
```bash
git add submodules/SaveToCameraRoll/
git commit -m "$(cat <<'EOF'
SaveToCameraRoll: migrate resource property to EngineMediaResource and drop Postbox
Swaps the single MediaResource? property for EngineMediaResource?,
wrapping/unwrapping at boundaries. With the only Postbox reference
gone, removes `import Postbox` and the Bazel dep.
Behavior-preserving.
Part of the MediaResource -> EngineMediaResource migration (wave 2).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
If the import was kept:
```bash
git add submodules/SaveToCameraRoll/Sources/SaveToCameraRoll.swift
git commit -m "$(cat <<'EOF'
SaveToCameraRoll: migrate resource property to EngineMediaResource
Swaps the single MediaResource? property for EngineMediaResource?,
wrapping/unwrapping at boundaries. import Postbox remains because
other identifiers still need it. Behavior-preserving.
Part of the MediaResource -> EngineMediaResource migration (wave 2).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```
---
## Task 9: Wave-2 completion verification
**Files:** No code changes.
- [ ] **Step 1: Commit-log check**
```bash
git log --oneline master..HEAD # or whatever branch this was executed on
```
Expected commits (some may be absent if tasks abandoned):
- `CLAUDE.md: record TelegramCore-no-UIKit rule and EngineMediaResource migration pattern`
- `TelegramCore: migrate peer-photo facade to EngineMediaResource`
- `TelegramCore: migrate account-photo facade to EngineMediaResource`
- `TelegramCore: migrate updateContactPhoto facade to EngineMediaResource`
- `TelegramCore: migrate Auth.uploadedPeerVideo facade to EngineMediaResource`
- `MapResourceToAvatarSizes: migrate to EngineMediaResource and drop Postbox`
- `AuthorizationUI: migrate avatar-video signal type to EngineMediaResource`
- `SaveToCameraRoll: migrate resource property to EngineMediaResource[...]`
- [ ] **Step 2: Public-API leak check**
```bash
grep -nE "^\s*public func .*: MediaResource|public func .*MediaResource, \[" \
submodules/TelegramCore/Sources/TelegramEngine/
```
Expected: no matches in the facade files touched by Tasks 2–5 (`TelegramEngine/Peers/TelegramEnginePeers.swift`, `TelegramEngine/AccountData/TelegramEngineAccountData.swift`, `TelegramEngine/Contacts/TelegramEngineContacts.swift`, `TelegramEngine/Auth/TelegramEngineAuth.swift`). Other TelegramEngine files may still leak `MediaResource` — those are for future waves.
- [ ] **Step 3: Final full build from clean state**
Run the full build. Expected: PASS (cached, fast).
- [ ] **Step 4: No commit.** Verification only.
---
## Future waves (not in this plan)
Ranked consumer modules by MediaResource/TelegramMediaResource reference count (from `grep -rE "\\b(MediaResource|TelegramMediaResource)\\b"` over `submodules/<M>/Sources/`, excluding TelegramCore/Postbox). Classifications are preliminary and must be re-audited at the start of each future wave.
| Refs | Module | Future-wave notes |
| --- | --- | --- |
| 2 | ChatPresentationInterfaceState | Public struct field `resource: TelegramMediaResource` — needs caller audit. |
| 2 | ItemListStickerPackItem | Enum case leaks `MediaResource` — needs caller audit. |
| 2 | TelegramCallsUI | Signal<TelegramMediaResource, …> locals; mostly type-refs. |
| 3 | LegacyMediaPickerUI | `thumbnailResource: TelegramMediaResource?` internal properties — likely safe. |
| 3 | ReactionSelectionNode | `customEffectResource: MediaResource?` in public func — caller audit. |
| 3 | TelegramAnimatedStickerNode | `public init(postbox: Postbox, resource: MediaResource, …)` + `public convenience init(account: Account, …)` — umbrella-type leaks; needs a paired wave. |
| 4 | GalleryUI | `private func setupStatus(resource: MediaResource)` — internal, 4 files. |
| 5 | StickerResources | Multiple public funcs take `postbox: Postbox, resource: MediaResource` / `mediaBox: MediaBox`. |
| 6 | PhotoResources | Similar to StickerResources; also `securePhoto(account: Account, resource: TelegramMediaResource, …)`. |
| 7 | MediaPlayer | `mediaBox: MediaBox, resource: MediaResource` in public init — umbrella leaks. |
| 7 | WebSearchUI | `thumbnailResource: TelegramMediaResource?` in multiple structs/inits. |
| 8 | AccountContext | Protocol surface — audit carefully. |
| 8 | SoftwareVideo | Public init takes `mediaBox: MediaBox` + `resource: MediaResource`. |
| 12 | LocalMediaResources | Contains `VideoLibraryMediaResource: TelegramMediaResource` — blocked for conformance. |
| 14 | LegacyDataImport | Legacy path; audit scope. |
| 25 | PassportUI | Large surface; break into multiple tasks. |
| 36 | TelegramUI | Umbrella module; never as one wave. |
**Blocked-by-conformance modules, explicitly out of all waves:**
- `submodules/ICloudResources/Sources/ICloudResources.swift` — `ICloudFileResource`
- `submodules/InstantPageUI/Sources/InstantPageExternalMediaResource.swift` — `InstantPageExternalMediaResource`
- `submodules/LocalMediaResources/Sources/LocalMediaResources.swift` — `VideoLibraryMediaResource`
- `submodules/TelegramUniversalVideoContent/Sources/YoutubeEmbedImplementation.swift` — `YoutubeEmbedStoryboardMediaResource`
These classes must conform to `TelegramMediaResource` to satisfy the PostboxCoding serialization contract. They remain `import Postbox`.
---
## What's explicitly NOT in this plan
- Adding opt-in `EngineMediaResource` overloads alongside raw-`MediaResource` overloads. The facade is changed in place.
- Touching any class conforming to `TelegramMediaResource`.
- Editing `TelegramUI`, `PassportUI`, `LegacyDataImport`, or the other heavy-ref modules in the Future-waves table beyond what the Phase-1 call-site migrations require.
- Importing UIKit/Display into TelegramCore under any circumstance.
- Modifying `_internal_*` functions in TelegramCore — they stay on raw `MediaResource`.
- Any behavior change, performance tweak, or "while we're here" cleanup.

968
docs/superpowers/plans/2026-04-18-postbox-to-telegramengine-wave-3.md
View file

@ -1,968 +0,0 @@
# Postbox → TelegramEngine Wave 3 Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Add three thin forwarding methods on `TelegramEngine.Resources` for fetch/status/data, then migrate `SaveToCameraRoll` to use them, drop `import Postbox` from that module, and update all 23 call sites.
**Architecture:** Two atomic commits on branch `refactor/postbox-to-engine-wave-3`. C1 adds the facades in isolation. C2 changes `SaveToCameraRoll`'s public API (drops the `postbox:` parameter, switches `FetchMediaDataState.data` payload from `MediaResourceData` to `EngineMediaResource.ResourceData`), rewrites the module's internals via `context.engine.resources.*`, removes `import Postbox`, and updates every caller in the same commit so the tree remains buildable.
**Tech Stack:** Swift / Bazel. No unit tests exist in this repo — verification is a full project build.
**Spec:** [docs/superpowers/specs/2026-04-18-postbox-to-telegramengine-wave-3-design.md](docs/superpowers/specs/2026-04-18-postbox-to-telegramengine-wave-3-design.md)
**Build command (use for every "full build" step):**
```bash
source ~/.zshrc 2>/dev/null; PATH=/opt/homebrew/opt/ruby/bin:`gem environment gemdir`/bin:$PATH python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber 1 --configuration debug_sim_arm64
```
The prefix `source ~/.zshrc 2>/dev/null;` is required because `TELEGRAM_CODESIGNING_GIT_PASSWORD` lives in `~/.zshrc` and the bash tool does not source shell config by default.
---
## Task 1: Add `TelegramEngine.Resources.fetch/status/data` facades (C1)
**Files:**
- Modify: [submodules/TelegramCore/Sources/TelegramEngine/Resources/TelegramEngineResources.swift:415-417](submodules/TelegramCore/Sources/TelegramEngine/Resources/TelegramEngineResources.swift#L415)
- [ ] **Step 1: Insert the three facade methods**
Open `submodules/TelegramCore/Sources/TelegramEngine/Resources/TelegramEngineResources.swift`. Find the existing `applicationIcons()` method (currently the last method in the `Resources` class). Insert the three new methods immediately after it, still inside the `final class Resources` brace (before the closing `}`):
```swift
public func applicationIcons() -> Signal<TelegramApplicationIcons, NoError> {
return _internal_applicationIcons(account: account)
}
public func fetch(
reference: MediaResourceReference,
userLocation: MediaResourceUserLocation,
userContentType: MediaResourceUserContentType
) -> Signal<FetchResourceSourceType, FetchResourceError> {
return fetchedMediaResource(
mediaBox: self.account.postbox.mediaBox,
userLocation: userLocation,
userContentType: userContentType,
reference: reference
)
}
public func status(
resource: EngineMediaResource
) -> Signal<EngineMediaResource.FetchStatus, NoError> {
return self.account.postbox.mediaBox.resourceStatus(resource._asResource())
|> map { EngineMediaResource.FetchStatus($0) }
}
public func data(
resource: EngineMediaResource,
pathExtension: String?,
waitUntilFetchStatus: Bool
) -> Signal<EngineMediaResource.ResourceData, NoError> {
return self.account.postbox.mediaBox.resourceData(
resource._asResource(),
pathExtension: pathExtension,
option: .complete(waitUntilFetchStatus: waitUntilFetchStatus)
)
|> map { EngineMediaResource.ResourceData($0) }
}
}
}
```
- [ ] **Step 2: Full build — verify C1 compiles cleanly**
Run the build command from the header. Expected: build succeeds with no errors. If a `signature mismatch` or `cannot find 'fetchedMediaResource'` error appears, double-check that `FetchedMediaResource.swift` and `MediaBox.swift` already export the referenced symbols (they do as of this plan's writing — no import changes are needed in `TelegramEngineResources.swift`, which already imports `Postbox`, `SwiftSignalKit`, and `TelegramApi`).
- [ ] **Step 3: Commit C1**
```bash
git add submodules/TelegramCore/Sources/TelegramEngine/Resources/TelegramEngineResources.swift
git commit -m "$(cat <<'EOF'
TelegramEngine.Resources: add fetch/status/data facades
Thin forwarders over MediaBox for the narrow surface SaveToCameraRoll
needs. Takes EngineMediaResource and returns EngineMediaResource-typed
results where applicable. Wave-3 groundwork.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
---
## Task 2: Pre-flight — re-inventory call sites and verify ShareController postbox
No code changes in this task. Its purpose is to catch drift from the spec's inventory before editing code, per CLAUDE.md's "inventory at execution time" guidance.
**Files:** (read-only)
- Spec inventory: [docs/superpowers/specs/2026-04-18-postbox-to-telegramengine-wave-3-design.md](docs/superpowers/specs/2026-04-18-postbox-to-telegramengine-wave-3-design.md)
- Definition to verify: `submodules/ShareController/Sources/ShareController.swift` around line 2403 and `ShareControllerAppAccountContext`
- [ ] **Step 1: Re-grep the current call-site set**
Run:
```bash
grep -rnE "(fetchMediaData|saveToCameraRoll|copyToPasteboard)\(" submodules --include="*.swift" \
| grep -v "SaveToCameraRoll/Sources/SaveToCameraRoll.swift" \
| grep -v "private func saveToCameraRoll" \
| grep -v "self\?\.saveToCameraRoll\|strongSelf\.saveToCameraRoll"
```
Expected output has exactly 23 lines across 14 files, matching the spec's inventory table:
| Module | File | Expected count |
|---|---|---|
| InstantPageUI | `Sources/InstantPageControllerNode.swift` | 2 |
| LegacyMediaPickerUI | `Sources/LegacyAttachmentMenu.swift` | 2 |
| LegacyMediaPickerUI | `Sources/LegacyAvatarPicker.swift` | 2 |
| BrowserUI | `Sources/BrowserInstantPageContent.swift` | 2 |
| GalleryUI | `Sources/Items/ChatImageGalleryItem.swift` | 2 |
| GalleryUI | `Sources/Items/UniversalVideoGalleryItem.swift` | 3 |
| TelegramUI (MediaEditorScreen) | `Components/MediaEditorScreen/Sources/MediaEditorScreen.swift` | 1 |
| TelegramUI (MediaEditorScreen) | `Components/MediaEditorScreen/Sources/EditStories.swift` | 1 |
| TelegramUI (ChatQrCodeScreen) | `Components/Chat/ChatQrCodeScreen/Sources/ChatQrCodeScreen.swift` | 1 |
| TelegramUI (StoryContainer) | `Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerComponent.swift` | 1 |
| TelegramUI (PeerInfoStoryGrid) | `Components/PeerInfo/PeerInfoStoryGridScreen/Sources/PeerInfoStoryGridScreen.swift` | 1 |
| TelegramUI | `Sources/ChatInterfaceStateContextMenus.swift` | 1 |
| TelegramUI | `Sources/SaveMediaToFiles.swift` | 1 |
| ShareController | `Sources/ShareController.swift` | 3 |
If the count or file list has drifted meaningfully from this table, **stop**, report the drift, and request a spec revision before continuing. Additions of one or two call sites can be folded in; larger drift should pause the wave.
- [ ] **Step 2: Verify `ShareController:2406` postbox equivalence**
Read `submodules/ShareController/Sources/ShareController.swift` lines 2395–2420. The private helper `saveToCameraRoll(messages:completion:)` contains `let postbox = self.currentContext.stateManager.postbox` and passes it to `SaveToCameraRoll.saveToCameraRoll`. After the migration, `SaveToCameraRoll` will use `context.account.postbox.mediaBox` internally.
The enclosing function gates on `self.currentContext as? ShareControllerAppAccountContext`. In that code path, `accountContext.context.account` is the `Account` that `ShareControllerAppAccountContext` was built from, and `self.currentContext.stateManager` is that same account's state manager. Therefore `accountContext.context.account.postbox === self.currentContext.stateManager.postbox`.
Confirm this by reading the definition of `ShareControllerAppAccountContext` in `submodules/AccountContext/Sources/ShareController.swift` (or the file where it's defined — grep for `ShareControllerAppAccountContext` to locate). If the `stateManager` there is derived from the same `account` whose `postbox` is reachable via `context.account.postbox`, treat the two as equivalent and proceed. If they can diverge (e.g., share-extension account switching creates a separate state manager), **stop** and abandon the ShareController:2406 edit with a recorded reason before continuing — the rest of the wave still applies.
- [ ] **Step 3: Record verification outcome**
Write a one-line note in the executor's task log noting either "ShareController:2406 postbox equivalence confirmed" or "ShareController:2406 abandoned — reason: ...". No commit.
---
## Task 3: Migrate `SaveToCameraRoll` module
This task changes the module's public API and internals. Build will fail after this task because all callers are still passing `postbox:` — that's expected and will be fixed in Task 4, which must land in the same commit as this task.
**Files:**
- Modify: [submodules/SaveToCameraRoll/Sources/SaveToCameraRoll.swift](submodules/SaveToCameraRoll/Sources/SaveToCameraRoll.swift) (entire file rewritten as shown below)
- [ ] **Step 1: Rewrite `SaveToCameraRoll.swift`**
Replace the file's contents with:
```swift
import Foundation
import UIKit
import SwiftSignalKit
import TelegramCore
import Photos
import Display
import MobileCoreServices
import DeviceAccess
import AccountContext
import LegacyComponents
public enum FetchMediaDataState {
case progress(Float)
case data(EngineMediaResource.ResourceData)
}
public func fetchMediaData(context: AccountContext, userLocation: MediaResourceUserLocation, customUserContentType: MediaResourceUserContentType? = nil, mediaReference: AnyMediaReference, forceVideo: Bool = false) -> Signal<(FetchMediaDataState, Bool), NoError> {
var resource: TelegramMediaResource?
var isImage = true
var fileExtension: String?
var userContentType: MediaResourceUserContentType = .other
if let image = mediaReference.media as? TelegramMediaImage {
userContentType = .image
if let video = image.videoRepresentations.last, forceVideo {
resource = video.resource
isImage = false
} else if let representation = largestImageRepresentation(image.representations) {
resource = representation.resource
}
} else if let file = mediaReference.media as? TelegramMediaFile {
userContentType = MediaResourceUserContentType(file: file)
resource = file.resource
if file.isVideo || file.mimeType.hasPrefix("video/") {
isImage = false
}
let maybeExtension = ((file.fileName ?? "") as NSString).pathExtension
if !maybeExtension.isEmpty {
fileExtension = maybeExtension
}
} else if let webpage = mediaReference.media as? TelegramMediaWebpage, case let .Loaded(content) = webpage.content {
if let file = content.file {
resource = file.resource
if file.isVideo {
isImage = false
}
} else if let image = content.image {
if let representation = largestImageRepresentation(image.representations) {
resource = representation.resource
}
}
}
if let customUserContentType {
userContentType = customUserContentType
}
if let resource = resource {
let engineResource = EngineMediaResource(resource)
let fetchedData: Signal<FetchMediaDataState, NoError> = Signal { subscriber in
let fetched = context.engine.resources.fetch(
reference: mediaReference.resourceReference(resource),
userLocation: userLocation,
userContentType: userContentType
).start()
let status = context.engine.resources.status(resource: engineResource).start(next: { status in
switch status {
case .Local:
subscriber.putNext(.progress(1.0))
case .Remote:
subscriber.putNext(.progress(0.0))
case let .Fetching(_, progress):
subscriber.putNext(.progress(progress))
case let .Paused(progress):
subscriber.putNext(.progress(progress))
}
})
let data = context.engine.resources.data(
resource: engineResource,
pathExtension: fileExtension,
waitUntilFetchStatus: true
).start(next: { next in
subscriber.putNext(.data(next))
}, completed: {
subscriber.putCompletion()
})
return ActionDisposable {
fetched.dispose()
status.dispose()
data.dispose()
}
}
return fetchedData
|> map { data in
return (data, isImage)
}
} else {
return .complete()
}
}
public func saveToCameraRoll(context: AccountContext, userLocation: MediaResourceUserLocation, customUserContentType: MediaResourceUserContentType? = nil, mediaReference: AnyMediaReference, video: AnyMediaReference? = nil) -> Signal<Float, NoError> {
let mediaData: Signal<(FetchMediaDataState, Bool), NoError> = fetchMediaData(context: context, userLocation: userLocation, customUserContentType: customUserContentType, mediaReference: mediaReference)
let videoData: Signal<FetchMediaDataState?, NoError>
if let video {
videoData = fetchMediaData(context: context, userLocation: userLocation, customUserContentType: customUserContentType, mediaReference: video)
|> map { state, _ in
return state
}
|> map(Optional.init)
} else {
videoData = .single(nil)
}
return combineLatest(
queue: Queue.mainQueue(),
mediaData,
videoData
)
|> mapToSignal { stateAndIsImage, videoStateAndIsImage -> Signal<Float, NoError> in
let isImage = stateAndIsImage.1
var mainData: EngineMediaResource.ResourceData?
var videoData: EngineMediaResource.ResourceData?
var waitForVideo = false
if let videoState = videoStateAndIsImage {
switch videoState {
case let .progress(value):
return .single(value * 0.95)
case let .data(data):
videoData = data
}
switch stateAndIsImage.0 {
case let .progress(value):
return .single(0.95 + 0.05 * value)
case let .data(data):
mainData = data
}
waitForVideo = true
} else {
switch stateAndIsImage.0 {
case let .progress(value):
return .single(value)
case let .data(data):
mainData = data
}
}
if let mainData, mainData.isComplete, videoData != nil || !waitForVideo {
return Signal<Float, NoError> { subscriber in
DeviceAccess.authorizeAccess(to: .mediaLibrary(.save), presentationData: context.sharedContext.currentPresentationData.with { $0 }, present: { c, a in
context.sharedContext.presentGlobalController(c, a)
}, openSettings: context.sharedContext.applicationBindings.openSettings, { authorized in
if !authorized {
subscriber.putCompletion()
return
}
let tempVideoPath = NSTemporaryDirectory() + "\(Int64.random(in: Int64.min ... Int64.max)).mp4"
if isImage, let videoData, let imageData = try? Data(contentsOf: URL(fileURLWithPath: mainData.path)) {
let id = UUID().uuidString
let jpegWithID = addAssetIdentifierToJPEG(imageData, assetIdentifier: id)!
let outputVideoURL = URL(fileURLWithPath: NSTemporaryDirectory() + "\(id).mov")
try? FileManager.default.copyItem(atPath: videoData.path, toPath: tempVideoPath)
addAssetIdentifierToVideo(inputURL: URL(fileURLWithPath: tempVideoPath), outputURL: outputVideoURL, assetIdentifier: id) { success in
guard success else { return }
PHPhotoLibrary.shared().performChanges({
let request = PHAssetCreationRequest.forAsset()
request.addResource(with: .photo, data: jpegWithID, options: nil)
request.addResource(with: .pairedVideo, fileURL: outputVideoURL, options: nil)
}, completionHandler: { _, error in
let _ = try? FileManager.default.removeItem(atPath: tempVideoPath)
subscriber.putNext(1.0)
subscriber.putCompletion()
})
}
} else {
PHPhotoLibrary.shared().performChanges({
if isImage {
if let imageData = try? Data(contentsOf: URL(fileURLWithPath: mainData.path)) {
PHAssetCreationRequest.forAsset().addResource(with: .photo, data: imageData, options: nil)
}
} else {
if let _ = try? FileManager.default.copyItem(atPath: mainData.path, toPath: tempVideoPath) {
PHAssetChangeRequest.creationRequestForAssetFromVideo(atFileURL: URL(fileURLWithPath: tempVideoPath))
}
}
}, completionHandler: { _, error in
if let error {
print("\(error)")
}
let _ = try? FileManager.default.removeItem(atPath: tempVideoPath)
subscriber.putNext(1.0)
subscriber.putCompletion()
})
}
})
return ActionDisposable {
}
}
} else {
return .complete()
}
}
}
public func copyToPasteboard(context: AccountContext, userLocation: MediaResourceUserLocation, mediaReference: AnyMediaReference) -> Signal<Void, NoError> {
return fetchMediaData(context: context, userLocation: userLocation, mediaReference: mediaReference)
|> mapToSignal { state, isImage -> Signal<Void, NoError> in
if case let .data(data) = state, data.isComplete {
return Signal<Void, NoError> { subscriber in
let pasteboard = UIPasteboard.general
if mediaReference.media is TelegramMediaImage {
if let fileData = try? Data(contentsOf: URL(fileURLWithPath: data.path), options: .mappedIfSafe) {
pasteboard.setData(fileData, forPasteboardType: kUTTypeJPEG as String)
}
}
subscriber.putNext(Void())
subscriber.putCompletion()
return EmptyDisposable
}
} else {
return .complete()
}
}
|> mapToSignal { _ -> Signal<Void, NoError> in return .complete() }
}
private func addAssetIdentifierToJPEG(_ imageData: Data, assetIdentifier: String) -> Data? {
guard let source = CGImageSourceCreateWithData(imageData as CFData, nil), let uti = CGImageSourceGetType(source), let cgImage = CGImageSourceCreateImageAtIndex(source, 0, nil) else {
return nil
}
let mutableData = NSMutableData()
guard let destination = CGImageDestinationCreateWithData(mutableData, uti, 1, nil) else {
return nil
}
var metadata = CGImageSourceCopyPropertiesAtIndex(source, 0, nil) as? [String: Any] ?? [:]
var maker = metadata[kCGImagePropertyMakerAppleDictionary as String] as? [String: Any] ?? [:]
maker["17"] = assetIdentifier
metadata[kCGImagePropertyMakerAppleDictionary as String] = maker
CGImageDestinationAddImage(destination, cgImage, metadata as CFDictionary)
CGImageDestinationFinalize(destination)
return mutableData as Data
}
private func addAssetIdentifierToVideo(inputURL: URL, outputURL: URL, assetIdentifier: String, completion: @escaping (Bool) -> Void) {
let asset = AVAsset(url: inputURL)
guard let exportSession = AVAssetExportSession(asset: asset, presetName: AVAssetExportPresetPassthrough) else {
completion(false)
return
}
let identifierItem = AVMutableMetadataItem()
identifierItem.keySpace = .quickTimeMetadata
identifierItem.key = AVMetadataKey.quickTimeMetadataKeyContentIdentifier as NSString
identifierItem.value = assetIdentifier as NSString
let stillImageTimeItem = AVMutableMetadataItem()
let keyStillImageTime = "com.apple.quicktime.still-image-time"
let keySpaceQuickTimeMetadata = "mdta"
stillImageTimeItem.key = keyStillImageTime as (NSCopying & NSObjectProtocol)?
stillImageTimeItem.keySpace = AVMetadataKeySpace(rawValue: keySpaceQuickTimeMetadata)
stillImageTimeItem.value = 0 as (NSCopying & NSObjectProtocol)?
stillImageTimeItem.dataType = "com.apple.metadata.datatype.int8"
exportSession.outputURL = outputURL
exportSession.outputFileType = .mov
exportSession.metadata = [identifierItem, stillImageTimeItem]
exportSession.shouldOptimizeForNetworkUse = true
exportSession.exportAsynchronously {
completion(exportSession.status == .completed)
}
}
```
The key differences from the original file:
1. `import Postbox` — removed.
2. `FetchMediaDataState.data(MediaResourceData)` → `FetchMediaDataState.data(EngineMediaResource.ResourceData)`.
3. Three public functions drop their `postbox: Postbox` parameter.
4. `var resource: MediaResource?` → `var resource: TelegramMediaResource?`.
5. Inside `fetchMediaData`: build an `EngineMediaResource(resource)` once, and call `context.engine.resources.fetch / status / data` instead of `fetchedMediaResource(...)` / `postbox.mediaBox.resourceStatus(...)` / `postbox.mediaBox.resourceData(...)`.
6. `var mainData: MediaResourceData?` / `var videoData: MediaResourceData?` → `var ...: EngineMediaResource.ResourceData?`.
7. `mainData.complete` → `mainData.isComplete`. `data.complete` (in `copyToPasteboard`) → `data.isComplete`. Field `data.path` is unchanged.
- [ ] **Step 2: Do not build yet — proceed to Task 4**
Builds will fail until every caller in Task 4 is migrated. Do not run the build command here. No commit yet either — Task 3 and Task 4 share a single atomic commit in Task 5.
---
## Task 4: Update all 23 call sites
Every call site does one or both of two edits:
- **Edit A (all 23 sites):** drop `postbox: someExpression,` from the argument list.
- **Edit B (the 7 sites that destructure `fetchMediaData`):** rename `.complete` → `.isComplete` on the destructured data value; `.path` stays the same.
Each sub-step below is one file. No builds between files. No commit. Task 5 builds everything together.
**Sub-task 4.1 — InstantPageUI**
- [ ] **File:** [submodules/InstantPageUI/Sources/InstantPageControllerNode.swift](submodules/InstantPageUI/Sources/InstantPageControllerNode.swift)
At line 1027, replace:
```swift
let _ = copyToPasteboard(context: strongSelf.context, postbox: strongSelf.context.account.postbox, userLocation: strongSelf.sourceLocation.userLocation, mediaReference: .standalone(media: media)).start()
```
with:
```swift
let _ = copyToPasteboard(context: strongSelf.context, userLocation: strongSelf.sourceLocation.userLocation, mediaReference: .standalone(media: media)).start()
```
At line 1032, replace:
```swift
let _ = saveToCameraRoll(context: strongSelf.context, postbox: strongSelf.context.account.postbox, userLocation: strongSelf.sourceLocation.userLocation, mediaReference: .standalone(media: media)).start()
```
with:
```swift
let _ = saveToCameraRoll(context: strongSelf.context, userLocation: strongSelf.sourceLocation.userLocation, mediaReference: .standalone(media: media)).start()
```
**Sub-task 4.2 — LegacyMediaPickerUI / LegacyAttachmentMenu.swift** (destructures)
- [ ] **File:** [submodules/LegacyMediaPickerUI/Sources/LegacyAttachmentMenu.swift](submodules/LegacyMediaPickerUI/Sources/LegacyAttachmentMenu.swift)
At line 173, replace:
```swift
let _ = (fetchMediaData(context: context, postbox: context.account.postbox, userLocation: .other, mediaReference: media)
```
with:
```swift
let _ = (fetchMediaData(context: context, userLocation: .other, mediaReference: media)
```
In the `.start` block that follows (around line 175), replace `data.complete` with `data.isComplete` (only the `.complete` boolean access — do not touch `data.path`).
At line 490, replace:
```swift
let _ = (fetchMediaData(context: context, postbox: context.account.postbox, userLocation: .other, mediaReference: editCurrentMedia)
```
with:
```swift
let _ = (fetchMediaData(context: context, userLocation: .other, mediaReference: editCurrentMedia)
```
In the destructuring block that follows (around line 492), replace `data.complete` with `data.isComplete`.
**Sub-task 4.3 — LegacyMediaPickerUI / LegacyAvatarPicker.swift** (destructures)
- [ ] **File:** [submodules/LegacyMediaPickerUI/Sources/LegacyAvatarPicker.swift](submodules/LegacyMediaPickerUI/Sources/LegacyAvatarPicker.swift)
At line 58, replace:
```swift
let imageSignal = fetchMediaData(context: context, postbox: context.account.postbox, userLocation: .other, mediaReference: media, forceVideo: false)
```
with:
```swift
let imageSignal = fetchMediaData(context: context, userLocation: .other, mediaReference: media, forceVideo: false)
```
In the `|> map` block immediately after (line ~60), replace `data.complete` with `data.isComplete`.
At line 67, replace:
```swift
let videoSignal = isVideo ? fetchMediaData(context: context, postbox: context.account.postbox, userLocation: .other, mediaReference: media, forceVideo: true)
```
with:
```swift
let videoSignal = isVideo ? fetchMediaData(context: context, userLocation: .other, mediaReference: media, forceVideo: true)
```
In the `|> map` block immediately after (line ~69), replace `data.complete` with `data.isComplete`.
**Sub-task 4.4 — BrowserUI / BrowserInstantPageContent.swift**
- [ ] **File:** [submodules/BrowserUI/Sources/BrowserInstantPageContent.swift](submodules/BrowserUI/Sources/BrowserInstantPageContent.swift)
At line 1175, replace:
```swift
let _ = copyToPasteboard(context: self.context, postbox: self.context.account.postbox, userLocation: self.sourceLocation.userLocation, mediaReference: .standalone(media: media)).start()
```
with:
```swift
let _ = copyToPasteboard(context: self.context, userLocation: self.sourceLocation.userLocation, mediaReference: .standalone(media: media)).start()
```
At line 1180, replace:
```swift
let _ = saveToCameraRoll(context: self.context, postbox: self.context.account.postbox, userLocation: self.sourceLocation.userLocation, mediaReference: .standalone(media: media)).start()
```
with:
```swift
let _ = saveToCameraRoll(context: self.context, userLocation: self.sourceLocation.userLocation, mediaReference: .standalone(media: media)).start()
```
**Sub-task 4.5 — GalleryUI / ChatImageGalleryItem.swift** (one destructures)
- [ ] **File:** [submodules/GalleryUI/Sources/Items/ChatImageGalleryItem.swift](submodules/GalleryUI/Sources/Items/ChatImageGalleryItem.swift)
At line 732, replace:
```swift
let _ = (fetchMediaData(context: context, postbox: context.account.postbox, userLocation: .other, mediaReference: media)
```
with:
```swift
let _ = (fetchMediaData(context: context, userLocation: .other, mediaReference: media)
```
In the `.start` block that follows (around line 734), replace `data.complete` with `data.isComplete`.
At line 758, replace:
```swift
let _ = (SaveToCameraRoll.saveToCameraRoll(context: context, postbox: context.account.postbox, userLocation: .peer(message.id.peerId), mediaReference: media)
```
with:
```swift
let _ = (SaveToCameraRoll.saveToCameraRoll(context: context, userLocation: .peer(message.id.peerId), mediaReference: media)
```
**Sub-task 4.6 — GalleryUI / UniversalVideoGalleryItem.swift**
- [ ] **File:** [submodules/GalleryUI/Sources/Items/UniversalVideoGalleryItem.swift](submodules/GalleryUI/Sources/Items/UniversalVideoGalleryItem.swift)
At line 3764, replace:
```swift
let saveSignal = SaveToCameraRoll.saveToCameraRoll(context: self.context, postbox: self.context.account.postbox, userLocation: .peer(message.id.peerId), mediaReference: saveFileReference)
```
with:
```swift
let saveSignal = SaveToCameraRoll.saveToCameraRoll(context: self.context, userLocation: .peer(message.id.peerId), mediaReference: saveFileReference)
```
At line 3810, replace:
```swift
let _ = (SaveToCameraRoll.saveToCameraRoll(context: self.context, postbox: self.context.account.postbox, userLocation: .peer(message.id.peerId), mediaReference: .message(message: MessageReference(message), media: file))
```
with:
```swift
let _ = (SaveToCameraRoll.saveToCameraRoll(context: self.context, userLocation: .peer(message.id.peerId), mediaReference: .message(message: MessageReference(message), media: file))
```
At line 3867, replace:
```swift
let _ = (SaveToCameraRoll.saveToCameraRoll(context: context, postbox: context.account.postbox, userLocation: .peer(message.id.peerId), mediaReference: .message(message: MessageReference(message), media: image), video: videoReference)
```
with:
```swift
let _ = (SaveToCameraRoll.saveToCameraRoll(context: context, userLocation: .peer(message.id.peerId), mediaReference: .message(message: MessageReference(message), media: image), video: videoReference)
```
**Sub-task 4.7 — TelegramUI / MediaEditorScreen / MediaEditorScreen.swift** (destructures)
- [ ] **File:** [submodules/TelegramUI/Components/MediaEditorScreen/Sources/MediaEditorScreen.swift](submodules/TelegramUI/Components/MediaEditorScreen/Sources/MediaEditorScreen.swift)
At line 5136, in the multi-line call starting with `let _ = (fetchMediaData(`, delete the line ` postbox: self.context.account.postbox,`. The remaining call should read:
```swift
let _ = (fetchMediaData(
context: self.context,
userLocation: .other,
mediaReference: file
) |> deliverOnMainQueue).start(next: { [weak self] state, _ in
```
Inside this closure, the destructuring is `if case let .data(data) = state { let path = data.path ... }` — `data.path` stays unchanged, and this site does not access `data.complete` (verified against the current file). No Edit B rename needed here.
**Sub-task 4.8 — TelegramUI / MediaEditorScreen / EditStories.swift** (destructures)
- [ ] **File:** [submodules/TelegramUI/Components/MediaEditorScreen/Sources/EditStories.swift](submodules/TelegramUI/Components/MediaEditorScreen/Sources/EditStories.swift)
At line 37, replace:
```swift
return fetchMediaData(context: context, postbox: context.account.postbox, userLocation: .peer(peerReference.id), customUserContentType: .story, mediaReference: .story(peer: peerReference, id: storyItem.id, media: media))
```
with:
```swift
return fetchMediaData(context: context, userLocation: .peer(peerReference.id), customUserContentType: .story, mediaReference: .story(peer: peerReference, id: storyItem.id, media: media))
```
At line 39 (inside the `mapToSignal`), replace:
```swift
guard case let .data(data) = value, data.complete else {
```
with:
```swift
guard case let .data(data) = value, data.isComplete else {
```
(`data.path` accesses below this line remain unchanged.)
**Sub-task 4.9 — TelegramUI / ChatQrCodeScreen / ChatQrCodeScreen.swift** (destructures)
- [ ] **File:** [submodules/TelegramUI/Components/Chat/ChatQrCodeScreen/Sources/ChatQrCodeScreen.swift](submodules/TelegramUI/Components/Chat/ChatQrCodeScreen/Sources/ChatQrCodeScreen.swift)
At line 2505, replace:
```swift
let _ = (fetchMediaData(context: context, postbox: context.account.postbox, userLocation: userLocation, mediaReference: AnyMediaReference.standalone(media: media))
```
with:
```swift
let _ = (fetchMediaData(context: context, userLocation: userLocation, mediaReference: AnyMediaReference.standalone(media: media))
```
At line 2507, replace:
```swift
guard case let .data(data) = value, data.complete else {
```
with:
```swift
guard case let .data(data) = value, data.isComplete else {
```
**Sub-task 4.10 — TelegramUI / StoryContainerScreen / StoryItemSetContainerComponent.swift**
- [ ] **File:** [submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerComponent.swift](submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerComponent.swift)
At line 5980, replace:
```swift
let disposable = (saveToCameraRoll(context: component.context, postbox: component.context.account.postbox, userLocation: .peer(peerReference.id), customUserContentType: .story, mediaReference: .story(peer: peerReference, id: component.slice.item.storyItem.id, media: component.slice.item.storyItem.media._asMedia()))
```
with:
```swift
let disposable = (saveToCameraRoll(context: component.context, userLocation: .peer(peerReference.id), customUserContentType: .story, mediaReference: .story(peer: peerReference, id: component.slice.item.storyItem.id, media: component.slice.item.storyItem.media._asMedia()))
```
**Sub-task 4.11 — TelegramUI / PeerInfoStoryGridScreen / PeerInfoStoryGridScreen.swift**
- [ ] **File:** [submodules/TelegramUI/Components/PeerInfo/PeerInfoStoryGridScreen/Sources/PeerInfoStoryGridScreen.swift](submodules/TelegramUI/Components/PeerInfo/PeerInfoStoryGridScreen/Sources/PeerInfoStoryGridScreen.swift)
At line 268, replace:
```swift
signals.append(saveToCameraRoll(context: component.context, postbox: component.context.account.postbox, userLocation: .other, mediaReference: .story(peer: peerReference, id: item.id, media: item.media._asMedia()))
```
with:
```swift
signals.append(saveToCameraRoll(context: component.context, userLocation: .other, mediaReference: .story(peer: peerReference, id: item.id, media: item.media._asMedia()))
```
**Sub-task 4.12 — TelegramUI / Sources / ChatInterfaceStateContextMenus.swift**
- [ ] **File:** [submodules/TelegramUI/Sources/ChatInterfaceStateContextMenus.swift](submodules/TelegramUI/Sources/ChatInterfaceStateContextMenus.swift)
At line 1419, replace:
```swift
let _ = (saveToCameraRoll(context: context, postbox: context.account.postbox, userLocation: .peer(message.id.peerId), mediaReference: mediaReference)
```
with:
```swift
let _ = (saveToCameraRoll(context: context, userLocation: .peer(message.id.peerId), mediaReference: mediaReference)
```
**Sub-task 4.13 — TelegramUI / Sources / SaveMediaToFiles.swift** (destructures)
- [ ] **File:** [submodules/TelegramUI/Sources/SaveMediaToFiles.swift](submodules/TelegramUI/Sources/SaveMediaToFiles.swift)
At line 27, replace:
```swift
var signal = fetchMediaData(context: context, postbox: context.account.postbox, userLocation: .other, mediaReference: fileReference.abstract)
```
with:
```swift
var signal = fetchMediaData(context: context, userLocation: .other, mediaReference: fileReference.abstract)
```
At line 63, replace:
```swift
if data.complete {
```
with:
```swift
if data.isComplete {
```
(`data.path` accesses in the block below remain unchanged.)
**Sub-task 4.14 — ShareController / ShareController.swift**
- [ ] **File:** [submodules/ShareController/Sources/ShareController.swift](submodules/ShareController/Sources/ShareController.swift)
At line 2406, after verifying Task 2's postbox-equivalence, replace:
```swift
return SaveToCameraRoll.saveToCameraRoll(context: context, postbox: postbox, userLocation: .peer(message.id.peerId), mediaReference: .message(message: MessageReference(message), media: media))
```
with:
```swift
return SaveToCameraRoll.saveToCameraRoll(context: context, userLocation: .peer(message.id.peerId), mediaReference: .message(message: MessageReference(message), media: media))
```
Also delete the now-unused local binding above (line 2403):
```swift
let postbox = self.currentContext.stateManager.postbox
```
(This line is used only by the `saveToCameraRoll` call on line 2406. If the build later flags it as unused instead of an error, leave it; but preferred is to remove the dead binding.)
At line 2432, replace:
```swift
self.controllerNode.transitionToProgressWithValue(signal: SaveToCameraRoll.saveToCameraRoll(context: context, postbox: context.account.postbox, userLocation: .other, mediaReference: .standalone(media: media)) |> map(Optional.init), dismissImmediately: true, completion: {})
```
with:
```swift
self.controllerNode.transitionToProgressWithValue(signal: SaveToCameraRoll.saveToCameraRoll(context: context, userLocation: .other, mediaReference: .standalone(media: media)) |> map(Optional.init), dismissImmediately: true, completion: {})
```
At line 2441, replace:
```swift
self.controllerNode.transitionToProgressWithValue(signal: SaveToCameraRoll.saveToCameraRoll(context: context, postbox: context.account.postbox, userLocation: .other, mediaReference: mediaReference) |> map(Optional.init), dismissImmediately: completion == nil, completion: completion ?? {})
```
with:
```swift
self.controllerNode.transitionToProgressWithValue(signal: SaveToCameraRoll.saveToCameraRoll(context: context, userLocation: .other, mediaReference: mediaReference) |> map(Optional.init), dismissImmediately: completion == nil, completion: completion ?? {})
```
(The abandonment branch: if Task 2's verification found `stateManager.postbox` and `account.postbox` are non-equivalent, skip the `line 2406` edit, leave `let postbox = self.currentContext.stateManager.postbox` in place, and revert Task 3's change to the `saveToCameraRoll` public signature only for this one callsite — which is impossible without duplicate signatures, so in that case abandon the entire wave and record the reason in a new commit to the plan.)
---
## Task 5: Full build and commit C2
- [ ] **Step 1: Run the full project build**
Run the build command from the header. Expected: build succeeds with no errors across all modules.
If there are failures, they fall into a few predictable categories and are fixed in place — do not split into another commit:
- **"cannot convert value of type 'Postbox' to expected argument type"** — a call site was missed. Grep again for `postbox: ` usages in the migrated files and fix.
- **"value of type 'EngineMediaResource.ResourceData' has no member 'complete'"** — an Edit B site was missed. Rename to `isComplete`.
- **"use of unresolved identifier 'fetchedMediaResource'" or similar inside `SaveToCameraRoll.swift`** — indicates `import Postbox` was dropped but a bare Postbox top-level function is still referenced. Replace the call with the engine facade introduced in Task 1.
- **Warnings about unused local `let postbox = ...`** — delete the binding.
Re-run the build after each fix until it succeeds.
- [ ] **Step 2: Stage all touched files**
```bash
git add \
submodules/SaveToCameraRoll/Sources/SaveToCameraRoll.swift \
submodules/InstantPageUI/Sources/InstantPageControllerNode.swift \
submodules/LegacyMediaPickerUI/Sources/LegacyAttachmentMenu.swift \
submodules/LegacyMediaPickerUI/Sources/LegacyAvatarPicker.swift \
submodules/BrowserUI/Sources/BrowserInstantPageContent.swift \
submodules/GalleryUI/Sources/Items/ChatImageGalleryItem.swift \
submodules/GalleryUI/Sources/Items/UniversalVideoGalleryItem.swift \
submodules/TelegramUI/Components/MediaEditorScreen/Sources/MediaEditorScreen.swift \
submodules/TelegramUI/Components/MediaEditorScreen/Sources/EditStories.swift \
submodules/TelegramUI/Components/Chat/ChatQrCodeScreen/Sources/ChatQrCodeScreen.swift \
submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerComponent.swift \
submodules/TelegramUI/Components/PeerInfo/PeerInfoStoryGridScreen/Sources/PeerInfoStoryGridScreen.swift \
submodules/TelegramUI/Sources/ChatInterfaceStateContextMenus.swift \
submodules/TelegramUI/Sources/SaveMediaToFiles.swift \
submodules/ShareController/Sources/ShareController.swift
```
- [ ] **Step 3: Verify the diff is clean**
Run:
```bash
git diff --staged --stat
```
Expected: exactly 15 files changed, with SaveToCameraRoll.swift having the largest diff (the full-file rewrite) and each call-site file showing small line-count changes.
- [ ] **Step 4: Commit C2**
```bash
git commit -m "$(cat <<'EOF'
SaveToCameraRoll: drop import Postbox via engine.resources facades
Migrates SaveToCameraRoll's three public functions to take context
only (no more postbox:), switches the FetchMediaDataState.data payload
from MediaResourceData to EngineMediaResource.ResourceData, rewrites
internals via TelegramEngine.Resources.fetch/status/data, and drops
import Postbox from the module. All 23 call sites across 14 files
updated in the same commit to keep the tree buildable.
Wave-3 of the Postbox -> TelegramEngine refactor.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 5: Verify branch log**
Run:
```bash
git log --oneline refactor/postbox-to-engine-wave-3 | head -5
```
Expected: the top two commits on the branch are `SaveToCameraRoll: drop import Postbox ...` (C2) and `TelegramEngine.Resources: add fetch/status/data facades` (C1), above the previous spec commits.
- [ ] **Step 6: Update CLAUDE.md tally**
Open `CLAUDE.md`, find the "Modules currently free of `import Postbox`" section, and add `SaveToCameraRoll (wave 3)` to the bullet list. Also add a "Wave 3 outcome (2026-04-18)" subsection documenting: three facades added on `TelegramEngine.Resources`, `SaveToCameraRoll` fully de-Postboxed, 23 call sites migrated. If any call site was abandoned in Task 2, record the reason here.
Commit:
```bash
git add CLAUDE.md
git commit -m "$(cat <<'EOF'
CLAUDE.md: record wave-3 outcome
Adds SaveToCameraRoll to the Postbox-free module tally and documents
the three new TelegramEngine.Resources facades added in wave 3.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
---
## Success criteria
- `submodules/SaveToCameraRoll/Sources/SaveToCameraRoll.swift` contains no `import Postbox`.
- `grep -rnE "(fetchMediaData|saveToCameraRoll|copyToPasteboard)\\(" submodules --include="*.swift" | grep "postbox:"` returns zero matches outside of the private `collectExternalShareResource`/`collectExternalShareItems` helpers in `ShareController.swift` (which take their own `postbox:` parameters unrelated to SaveToCameraRoll).
- Full build succeeds in `debug_sim_arm64` configuration.
- Three branch commits above the spec commits: C1 (facades), C2 (SaveToCameraRoll + callers), C3 (CLAUDE.md tally).

500
docs/superpowers/plans/2026-04-18-postbox-to-telegramengine-wave-4.md
View file

@ -1,500 +0,0 @@
# Postbox → TelegramEngine Wave 4 Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Migrate `TelegramEngine.Stickers.uploadSticker`'s public surface — `peer: Peer → EnginePeer`, `resource: MediaResource → EngineMediaResource`, `thumbnail: MediaResource? → EngineMediaResource?`, and `UploadStickerStatus.complete(CloudDocumentMediaResource, String) → .complete(EngineMediaResource, String)` — with one atomic commit touching the facade, the internal enum, and the two call sites.
**Architecture:** Two commits on branch `refactor/postbox-to-engine-wave-4`. C1 is the atomic four-file code change. C2 is the CLAUDE.md tally update. `_internal_uploadSticker` keeps its raw `Peer`/`MediaResource` signature; the facade does all the wrapping/unwrapping. One spec-allowed one-line exception: `_internal_uploadSticker` constructs `EngineMediaResource(uploadedResource)` at the `.complete(...)` result-construction site to keep `UploadStickerStatus` as a single enum instead of splitting into raw+engine variants.
**Tech Stack:** Swift / Bazel. No unit tests in this repo — verification is a full project build.
**Spec:** [docs/superpowers/specs/2026-04-18-postbox-to-telegramengine-wave-4-design.md](docs/superpowers/specs/2026-04-18-postbox-to-telegramengine-wave-4-design.md)
**Build command** (use for every "full build" step):
```bash
source ~/.zshrc 2>/dev/null; PATH=/opt/homebrew/opt/ruby/bin:`gem environment gemdir`/bin:$PATH python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber 1 --configuration debug_sim_arm64
```
The `source ~/.zshrc` prefix is required because `TELEGRAM_CODESIGNING_GIT_PASSWORD` lives in `~/.zshrc` and the bash tool does not source shell config by default. For a background build from the controller session, prefer `run_in_background: true` and monitor by tailing the task output file (subagent-spawned background builds orphan when the subagent shell terminates).
---
## Task 1: Pre-flight re-verification
No code changes. Purpose: re-confirm the facade call-site count and the MediaEditorScreen line numbers haven't drifted.
**Files:** (read-only)
- [ ] **Step 1: Re-grep facade call sites**
```bash
grep -rnE "\.uploadSticker\(" submodules --include="*.swift" \
| grep -v "/TelegramEngine/Stickers/" \
| grep -v "self\.uploadSticker\|strongSelf\.uploadSticker\|self\?\.uploadSticker"
```
Expected output: exactly 2 lines
- `submodules/ImportStickerPackUI/Sources/ImportStickerPackController.swift:91`
- `submodules/TelegramUI/Components/MediaEditorScreen/Sources/MediaEditorScreen.swift:8099`
If the count or line numbers have drifted meaningfully, stop and revise the plan before editing.
- [ ] **Step 2: Re-read MediaEditorScreen block**
```bash
sed -n '8080,8190p' submodules/TelegramUI/Components/MediaEditorScreen/Sources/MediaEditorScreen.swift
```
Visually confirm:
- Line ~8097 has `.complete(resource, mimeType)` inside an `if let resource = resource as? CloudDocumentMediaResource { … }` branch.
- Line ~8099 has `context.engine.stickers.uploadSticker(peer: peer._asPeer(), resource: resource, thumbnail: file.previewRepresentations.first?.resource, …)`.
- Line ~8105 has `case let .complete(resource, _):` destructuring the inner `.mapToSignal` status.
- Line ~8106 has `stickerFile(resource: resource, thumbnailResource: file.previewRepresentations.first?.resource, …)`.
- Line ~8119 has `ImportSticker(resource: .standalone(resource: resource), …)` inside `case let .createStickerPack(title):`.
- Line ~8138 has a second `ImportSticker(resource: .standalone(resource: resource), …)` inside `case let .addToStickerPack(pack, title):`.
- Line ~8178 has a second `case let .complete(resource, _):` in the outer `.startStandalone(next: …)` handler.
- Line ~8180 has `stickerFile(resource: resource, thumbnailResource: file.previewRepresentations.first?.resource, size: resource.size ?? 0, …)`.
- [ ] **Step 3: Confirm `stickerFile` signature**
```bash
grep -nE "^private func stickerFile\(" submodules/TelegramUI/Components/MediaEditorScreen/Sources/MediaEditorScreen.swift
```
Expected: `private func stickerFile(resource: TelegramMediaResource, thumbnailResource: TelegramMediaResource?, size: Int64, dimensions: PixelDimensions, duration: Double?, isVideo: Bool) -> TelegramMediaFile` at line ~9196. This confirms `stickerFile` takes `TelegramMediaResource` (requires `resource._asResource()` at every call).
- [ ] **Step 4: Confirm ImportStickerPackController's `peer` type**
```bash
sed -n '82,95p' submodules/ImportStickerPackUI/Sources/ImportStickerPackController.swift
```
Expected pattern:
```swift
let _ = (self.context.account.postbox.loadedPeerWithId(self.context.account.peerId)
|> deliverOnMainQueue).start(next: { [weak self] peer in
```
`postbox.loadedPeerWithId` returns `Signal<Peer, NoError>`. The local `peer` is therefore a raw `Peer`, not an `EnginePeer`. The call-site edit will need `EnginePeer(peer)` to wrap.
If any of these expectations fails to match the current source, stop and revise the plan.
---
## Task 2: Migrate `UploadStickerStatus` enum and internal wrap
No build; the project won't compile until Tasks 3–5 also land. Do not commit.
**File:** `submodules/TelegramCore/Sources/TelegramEngine/Stickers/ImportStickers.swift`
- [ ] **Step 1: Update enum payload (line 7–10)**
Replace:
```swift
public enum UploadStickerStatus {
case progress(Float)
case complete(CloudDocumentMediaResource, String)
}
```
with:
```swift
public enum UploadStickerStatus {
case progress(Float)
case complete(EngineMediaResource, String)
}
```
- [ ] **Step 2: Update the `.complete(...)` construction in `_internal_uploadSticker` (line ~97)**
Replace the line reading:
```swift
return .single(.complete(uploadedResource, file.mimeType))
```
with:
```swift
return .single(.complete(EngineMediaResource(uploadedResource), file.mimeType))
```
Nothing else in `_internal_uploadSticker` changes. In particular its parameter list (`peer: Peer, resource: MediaResource, thumbnail: MediaResource? = nil, …`) stays exactly as is.
---
## Task 3: Migrate the public facade signature
No build; no commit.
**File:** `submodules/TelegramCore/Sources/TelegramEngine/Stickers/TelegramEngineStickers.swift`
- [ ] **Step 1: Update the `uploadSticker` facade (line 85–87)**
Replace:
```swift
public func uploadSticker(peer: Peer, resource: MediaResource, thumbnail: MediaResource?, alt: String, dimensions: PixelDimensions, duration: Double?, mimeType: String) -> Signal<UploadStickerStatus, UploadStickerError> {
return _internal_uploadSticker(account: self.account, peer: peer, resource: resource, thumbnail: thumbnail, alt: alt, dimensions: dimensions, duration: duration, mimeType: mimeType)
}
```
with:
```swift
public func uploadSticker(peer: EnginePeer, resource: EngineMediaResource, thumbnail: EngineMediaResource?, alt: String, dimensions: PixelDimensions, duration: Double?, mimeType: String) -> Signal<UploadStickerStatus, UploadStickerError> {
return _internal_uploadSticker(account: self.account, peer: peer._asPeer(), resource: resource._asResource(), thumbnail: thumbnail?._asResource(), alt: alt, dimensions: dimensions, duration: duration, mimeType: mimeType)
}
```
No other method in `TelegramEngineStickers.swift` changes.
---
## Task 4: Migrate `ImportStickerPackController.swift:91`
No build; no commit.
**File:** `submodules/ImportStickerPackUI/Sources/ImportStickerPackController.swift`
- [ ] **Step 1: Update the facade call (line ~91)**
Replace:
```swift
signals.append(strongSelf.context.engine.stickers.uploadSticker(peer: peer, resource: resource._asResource(), thumbnail: nil, alt: sticker.emojis.first ?? "", dimensions: PixelDimensions(width: 512, height: 512), duration: nil, mimeType: sticker.mimeType)
```
with:
```swift
signals.append(strongSelf.context.engine.stickers.uploadSticker(peer: EnginePeer(peer), resource: resource, thumbnail: nil, alt: sticker.emojis.first ?? "", dimensions: PixelDimensions(width: 512, height: 512), duration: nil, mimeType: sticker.mimeType)
```
Two changes: `peer` (raw `Peer`) → `EnginePeer(peer)`, and `resource._asResource()` → `resource` (the local `resource` is an `EngineMediaResource`).
- [ ] **Step 2: Update the destructure re-wrap (line ~99)**
Replace:
```swift
case let .complete(resource, mimeType):
if ["application/x-tgsticker", "video/webm"].contains(mimeType) {
return (sticker.uuid, .verified, EngineMediaResource(resource))
} else {
```
with:
```swift
case let .complete(resource, mimeType):
if ["application/x-tgsticker", "video/webm"].contains(mimeType) {
return (sticker.uuid, .verified, resource)
} else {
```
One change: `EngineMediaResource(resource)` → `resource`. The destructured `resource` is now already an `EngineMediaResource`.
Nothing else in this file changes.
---
## Task 5: Migrate `MediaEditorScreen.swift` sticker-upload block
No build; no commit. This task touches multiple lines inside a single nested block (~8084–8190). The `UploadStickerStatus` payload migration cascades: wherever the code constructs or destructures `.complete(...)`, types change.
**File:** `submodules/TelegramUI/Components/MediaEditorScreen/Sources/MediaEditorScreen.swift`
- [ ] **Step 1: Wrap at the direct construction site (line ~8097)**
Replace the line reading:
```swift
return .single((.progress(1.0), nil)) |> then(.single((.complete(resource, mimeType), nil)))
```
with:
```swift
return .single((.progress(1.0), nil)) |> then(.single((.complete(EngineMediaResource(resource), mimeType), nil)))
```
Context: this is inside `if let resource = resource as? CloudDocumentMediaResource { … }`, so `resource` here is `CloudDocumentMediaResource`; the outer tuple's `UploadStickerStatus.complete` now takes `EngineMediaResource`.
- [ ] **Step 2: Migrate the facade call (line ~8099)**
Replace:
```swift
return context.engine.stickers.uploadSticker(peer: peer._asPeer(), resource: resource, thumbnail: file.previewRepresentations.first?.resource, alt: "", dimensions: dimensions, duration: duration, mimeType: mimeType)
```
with:
```swift
return context.engine.stickers.uploadSticker(peer: peer, resource: EngineMediaResource(resource), thumbnail: file.previewRepresentations.first.flatMap { EngineMediaResource($0.resource) }, alt: "", dimensions: dimensions, duration: duration, mimeType: mimeType)
```
Three changes: `peer._asPeer()` → `peer` (local is `EnginePeer`); `resource` → `EngineMediaResource(resource)` (local is raw `MediaResource` from the outer enum destructure); `file.previewRepresentations.first?.resource` → `file.previewRepresentations.first.flatMap { EngineMediaResource($0.resource) }`.
- [ ] **Step 3: Unwrap at inner-handler `stickerFile` call (line ~8106)**
Replace:
```swift
case let .complete(resource, _):
let file = stickerFile(resource: resource, thumbnailResource: file.previewRepresentations.first?.resource, size: file.size ?? 0, dimensions: dimensions, duration: file.duration, isVideo: isVideo)
```
with:
```swift
case let .complete(resource, _):
let file = stickerFile(resource: resource._asResource(), thumbnailResource: file.previewRepresentations.first?.resource, size: file.size ?? 0, dimensions: dimensions, duration: file.duration, isVideo: isVideo)
```
The destructured `resource` is now an `EngineMediaResource`. `stickerFile` (see line 9196) takes `TelegramMediaResource`, so unwrap with `._asResource()`. `file.previewRepresentations.first?.resource` is already a `TelegramMediaResource?` — no change there.
- [ ] **Step 4: Unwrap at `.createStickerPack` sticker construction (line ~8119)**
Replace:
```swift
case let .createStickerPack(title):
let sticker = ImportSticker(
resource: .standalone(resource: resource),
emojis: emojis,
dimensions: dimensions,
duration: duration,
mimeType: mimeType,
keywords: ""
)
```
with:
```swift
case let .createStickerPack(title):
let sticker = ImportSticker(
resource: .standalone(resource: resource._asResource()),
emojis: emojis,
dimensions: dimensions,
duration: duration,
mimeType: mimeType,
keywords: ""
)
```
`MediaResourceReference.standalone(resource:)` takes `MediaResource`; `resource` here is the `EngineMediaResource` destructured at line ~8105. Unwrap with `._asResource()`.
- [ ] **Step 5: Unwrap at `.addToStickerPack` sticker construction (line ~8138)**
Replace:
```swift
case let .addToStickerPack(pack, title):
let sticker = ImportSticker(
resource: .standalone(resource: resource),
emojis: emojis,
dimensions: dimensions,
duration: duration,
mimeType: mimeType,
keywords: ""
)
```
with:
```swift
case let .addToStickerPack(pack, title):
let sticker = ImportSticker(
resource: .standalone(resource: resource._asResource()),
emojis: emojis,
dimensions: dimensions,
duration: duration,
mimeType: mimeType,
keywords: ""
)
```
Same unwrap as Step 4.
- [ ] **Step 6: Unwrap at outer-handler `stickerFile` call (line ~8178–8180)**
Replace:
```swift
case let .complete(resource, _):
let navigationController = self.effectiveNavigationController as? NavigationController
let result: MediaEditorScreenImpl.Result
switch action {
case .update:
result = MediaEditorScreenImpl.Result(media: .sticker(file: file, emoji: emojis))
case .upload, .send:
let file = stickerFile(resource: resource, thumbnailResource: file.previewRepresentations.first?.resource, size: resource.size ?? 0, dimensions: dimensions, duration: self.preferredStickerDuration(), isVideo: isVideo)
```
with:
```swift
case let .complete(resource, _):
let rawResource = resource._asResource()
let navigationController = self.effectiveNavigationController as? NavigationController
let result: MediaEditorScreenImpl.Result
switch action {
case .update:
result = MediaEditorScreenImpl.Result(media: .sticker(file: file, emoji: emojis))
case .upload, .send:
let file = stickerFile(resource: rawResource, thumbnailResource: file.previewRepresentations.first?.resource, size: rawResource.size ?? 0, dimensions: dimensions, duration: self.preferredStickerDuration(), isVideo: isVideo)
```
Two changes: introduce `let rawResource = resource._asResource()` at the top of the `case let .complete(resource, _):` block, and use `rawResource` at both the `resource:` argument and the `size: rawResource.size ?? 0` read. (`EngineMediaResource` does not expose `.size`; only the raw `MediaResource` does.)
- [ ] **Step 7: Scan for any missed downstream use**
Run inside the repo:
```bash
sed -n '8080,8200p' submodules/TelegramUI/Components/MediaEditorScreen/Sources/MediaEditorScreen.swift | grep -nE "\bresource\b"
```
Skim the output. Every reference to the destructured `resource` inside the nested block (lines ~8084–8190) should either be the new `EngineMediaResource`-typed local or a wrapped/unwrapped form. If you spot a use that would still expect `CloudDocumentMediaResource`-specific members or raw `MediaResource` without the unwrap, stop and report.
---
## Task 6: Full build and commit C1
- [ ] **Step 1: Run the full project build**
Run the build command from the header. Expected: clean success.
Typical failure modes and fixes (do them inline — do not split into another commit):
- **"cannot convert value of type 'Peer' to expected argument type 'EnginePeer'"** — a call site was missed or the wrap is misplaced.
- **"value of type 'EngineMediaResource' has no member 'size'"** — Task 5 Step 6 wasn't applied (or similar `.size`/`.id.stringRepresentation`/`.isEqual` access on `EngineMediaResource`).
- **"cannot convert value of type 'EngineMediaResource' to expected argument type 'TelegramMediaResource'"** — an `._asResource()` is missing at a `stickerFile(...)` or `.standalone(resource:)` call.
- **"reference to enum case 'UploadStickerStatus.complete' requires that 'CloudDocumentMediaResource' conform to 'something'"** — a `.complete(...)` construction site wasn't migrated to pass `EngineMediaResource`.
Re-run the build after each fix.
- [ ] **Step 2: Stage the 4 files**
```bash
git add \
submodules/TelegramCore/Sources/TelegramEngine/Stickers/ImportStickers.swift \
submodules/TelegramCore/Sources/TelegramEngine/Stickers/TelegramEngineStickers.swift \
submodules/ImportStickerPackUI/Sources/ImportStickerPackController.swift \
submodules/TelegramUI/Components/MediaEditorScreen/Sources/MediaEditorScreen.swift
```
- [ ] **Step 3: Verify diff scope**
```bash
git diff --staged --stat
```
Expected: exactly 4 files staged, with MediaEditorScreen having the largest diff (~8 line changes), ImportStickers ~2, TelegramEngineStickers ~2, ImportStickerPackController ~2.
- [ ] **Step 4: Commit**
```bash
git commit -m "$(cat <<'EOF'
TelegramEngine.Stickers.uploadSticker: migrate to EnginePeer + EngineMediaResource
Public facade and UploadStickerStatus.complete payload now use
EnginePeer and EngineMediaResource instead of raw Peer / MediaResource
/ CloudDocumentMediaResource. _internal_uploadSticker stays on raw
Postbox types with one inline EngineMediaResource(uploadedResource)
construction at the .complete result site.
Both call sites (ImportStickerPackController, MediaEditorScreen)
updated atomically in the same commit.
Wave-4 of the Postbox -> TelegramEngine refactor.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 5: Verify branch state**
```bash
git log --oneline master..HEAD
```
Expected (newest at top):
- `<sha> TelegramEngine.Stickers.uploadSticker: migrate to EnginePeer + EngineMediaResource`
- `b6392bce7c docs(spec): wave-4 enumerate MediaEditorScreen downstream edits`
- `59a01b0d4d docs(spec): wave-4 TelegramEngine.Stickers.uploadSticker facade migration`
---
## Task 7: Update CLAUDE.md tally and commit C2
- [ ] **Step 1: Add Wave 4 outcome subsection**
Open `CLAUDE.md`. Find the "Wave 3 outcome (2026-04-18)" section (currently around line 96 onward). Insert a new subsection **after** Wave 3's outcome block and **before** "### Modules currently free of `import Postbox` (running tally)":
```markdown
### Wave 4 outcome (2026-04-18)
1 `TelegramEngine` facade migrated in place to `EnginePeer` + `EngineMediaResource` (signatures changed; `_internal_uploadSticker` keeps raw `Peer`/`MediaResource`):
- `TelegramEngine.Stickers.uploadSticker(peer: Peer → EnginePeer, resource: MediaResource → EngineMediaResource, thumbnail: MediaResource? → EngineMediaResource?, …)`
1 public enum payload migrated: `UploadStickerStatus.complete(CloudDocumentMediaResource, String)` → `.complete(EngineMediaResource, String)`. The internal `_internal_uploadSticker` constructs `EngineMediaResource(uploadedResource)` at the result site — a narrow, spec-allowed one-line deviation from "internal Postbox-facing stays raw", taken to keep `UploadStickerStatus` as a single public enum.
2 call sites migrated atomically with the facade:
- `submodules/ImportStickerPackUI/Sources/ImportStickerPackController.swift:91`
- `submodules/TelegramUI/Components/MediaEditorScreen/Sources/MediaEditorScreen.swift:8099` (plus ~5 cascading sites in the same enclosing block for the new `UploadStickerStatus.complete` payload)
No module becomes Postbox-free in this wave (both caller files import Postbox for unrelated reasons).
Plan: `docs/superpowers/plans/2026-04-18-postbox-to-telegramengine-wave-4.md`
```
- [ ] **Step 2: Remove the `uploadSticker` entry from "Known future-wave candidates"**
Still in `CLAUDE.md`, find the "Known future-wave candidates" list and delete this bullet (currently around line 143):
```markdown
- `TelegramEngine.Stickers.uploadSticker(peer: Peer, resource: MediaResource, thumbnail: MediaResource?, …)` — same MediaResource migration as wave 2, plus `peer: Peer` which would naturally migrate to `EnginePeer` at the same time. Self-contained to a small number of call sites.
```
Do not touch the other bullets in that list.
- [ ] **Step 3: Commit**
```bash
git add CLAUDE.md
git commit -m "$(cat <<'EOF'
CLAUDE.md: record wave-4 outcome
Documents the uploadSticker facade migration + UploadStickerStatus
payload change; removes uploadSticker from the future-wave candidates
list.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
---
## Success criteria
- `TelegramEngine.Stickers.uploadSticker`'s public signature references neither `Peer` nor `MediaResource` nor `CloudDocumentMediaResource`.
- `UploadStickerStatus.complete`'s payload is `(EngineMediaResource, String)`.
- `_internal_uploadSticker`'s signature is unchanged (still raw `Peer` / `MediaResource`).
- Full build succeeds in `debug_sim_arm64`.
- The two call sites (`ImportStickerPackController`, `MediaEditorScreen`) and the cascading sites within MediaEditorScreen's nested block compile against the new types.
- `CLAUDE.md` has a "Wave 4 outcome (2026-04-18)" subsection; the `uploadSticker` bullet is gone from "Known future-wave candidates".
- Branch `refactor/postbox-to-engine-wave-4` contains 4 commits above `master`: 2 docs (spec + spec fix), 1 code (C1), 1 tally (C2).

381
docs/superpowers/plans/2026-04-18-postbox-to-telegramengine-wave-5.md
View file

@ -1,381 +0,0 @@
# Postbox → TelegramEngine Wave 5 Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Migrate `uploadSecureIdFile`'s public surface to `(context:, engine: TelegramEngine, resource: EngineMediaResource)`, refactor `SecureIdVerificationDocumentsContext` to take `engine: TelegramEngine` in place of raw `Postbox` + `Network`, and drop `import Postbox` from that caller module. Land as one atomic code commit + one CLAUDE.md tally commit on branch `refactor/postbox-to-engine-wave-5`.
**Architecture:** Three files land together in C1 because the facade signature change, the caller class's stored-property change, and the one instantiation site are mutually breaking. The facade body inside TelegramCore continues to access raw Postbox types via `engine.account.postbox` / `engine.account.network` — CLAUDE.md's "internal Postbox-facing stays raw" rule applies to the body, while the public signature is the clean surface. C2 updates the CLAUDE.md tally and removes the wave-5-named bullet from "Known future-wave candidates".
**Tech Stack:** Swift / Bazel. No unit tests by repo policy — verification is a full project build.
**Spec:** [docs/superpowers/specs/2026-04-18-postbox-to-telegramengine-wave-5-design.md](docs/superpowers/specs/2026-04-18-postbox-to-telegramengine-wave-5-design.md)
**Build command** (use for every "full build" step):
```bash
source ~/.zshrc 2>/dev/null; PATH=/opt/homebrew/opt/ruby/bin:`gem environment gemdir`/bin:$PATH python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber 1 --configuration debug_sim_arm64
```
The `source ~/.zshrc` prefix is required because `TELEGRAM_CODESIGNING_GIT_PASSWORD` lives in `~/.zshrc` and the bash tool does not source shell config by default. For a long-running build, prefer `run_in_background: true` from the controller session (subagent-spawned background builds orphan when the subagent's shell terminates).
---
## Task 1: Pre-flight re-verification
No code changes. Confirms the inventory hasn't drifted.
- [ ] **Step 1: Re-grep `uploadSecureIdFile` call sites**
```bash
grep -rnE "uploadSecureIdFile\(" submodules --include="*.swift" | grep -v "/SecureId/"
```
Expected: exactly 1 match — `submodules/PassportUI/Sources/SecureIdVerificationDocumentsContext.swift:43`. If the count or file has drifted, stop and revise the plan.
- [ ] **Step 2: Re-grep `SecureIdVerificationDocumentsContext(...)` instantiation sites**
```bash
grep -rnE "SecureIdVerificationDocumentsContext\(" submodules --include="*.swift" | grep -v "final class SecureIdVerificationDocumentsContext"
```
Expected: exactly 1 match — `submodules/PassportUI/Sources/SecureIdDocumentFormControllerNode.swift:2172`. If drift, stop.
- [ ] **Step 3: Confirm `AccountContext.engine` protocol requirement**
```bash
grep -nE "var engine: TelegramEngine" submodules/AccountContext/Sources/AccountContext.swift
```
Expected: one line matching `var engine: TelegramEngine { get }` (the protocol requirement). This confirms `self.context.engine` will be available at the instantiation site in Task 4.
- [ ] **Step 4: Confirm `info.resource` type**
```bash
grep -nE "let resource:" submodules/PassportUI/Sources/SecureIdVerificationDocument.swift
```
Expected: two matches, both showing `resource: TelegramMediaResource`. Confirms `EngineMediaResource(info.resource)` will compile (the `EngineMediaResource(_:)` init takes `MediaResource`, which `TelegramMediaResource` inherits).
---
## Task 2: Migrate `uploadSecureIdFile`'s public facade and body
No build; no commit. Tasks 2–4 share one atomic commit in Task 5.
**File:** `submodules/TelegramCore/Sources/TelegramEngine/SecureId/UploadSecureIdFile.swift`
- [ ] **Step 1: Replace the function signature and body**
Find the `uploadSecureIdFile` function (currently starts at line 90). Replace the entire function (from `public func uploadSecureIdFile` through its closing `}`) with this version:
```swift
public func uploadSecureIdFile(context: SecureIdAccessContext, engine: TelegramEngine, resource: EngineMediaResource) -> Signal<UploadSecureIdFileResult, UploadSecureIdFileError> {
return engine.account.postbox.mediaBox.resourceData(resource._asResource())
|> mapError { _ -> UploadSecureIdFileError in
}
|> mapToSignal { next -> Signal<UploadSecureIdFileResult, UploadSecureIdFileError> in
if !next.complete {
return .complete()
}
guard let data = try? Data(contentsOf: URL(fileURLWithPath: next.path)) else {
return .fail(.generic)
}
guard let encryptedData = encryptedSecureIdFile(context: context, data: data) else {
return .fail(.generic)
}
return multipartUpload(network: engine.account.network, postbox: engine.account.postbox, source: .data(encryptedData.data), encrypt: false, tag: TelegramMediaResourceFetchTag(statsCategory: .image, userContentType: .image), hintFileSize: nil, hintFileIsLarge: false, forceNoBigParts: false)
|> mapError { _ -> UploadSecureIdFileError in
return .generic
}
|> mapToSignal { result -> Signal<UploadSecureIdFileResult, UploadSecureIdFileError> in
switch result {
case let .progress(value):
return .single(.progress(value))
case let .inputFile(.inputFile(fileData)):
return .single(.result(UploadedSecureIdFile(id: fileData.id, parts: fileData.parts, md5Checksum: fileData.md5Checksum, fileHash: encryptedData.hash, encryptedSecret: encryptedData.encryptedSecret), encryptedData.data))
default:
return .fail(.generic)
}
}
}
}
```
Changes from the original:
- Signature: `(context: SecureIdAccessContext, postbox: Postbox, network: Network, resource: MediaResource)` → `(context: SecureIdAccessContext, engine: TelegramEngine, resource: EngineMediaResource)`.
- Line 1 of body: `postbox.mediaBox.resourceData(resource)` → `engine.account.postbox.mediaBox.resourceData(resource._asResource())`.
- Inside the `mapToSignal`: `multipartUpload(network: network, postbox: postbox, ...)` → `multipartUpload(network: engine.account.network, postbox: engine.account.postbox, ...)`.
No other file in `TelegramCore/Sources/TelegramEngine/SecureId/` is touched. No imports change inside `UploadSecureIdFile.swift` — it continues to `import Foundation`, `import Postbox`, `import MtProtoKit`, `import SwiftSignalKit`, which remain correct (the body still uses raw Postbox types via `engine.account.postbox`).
---
## Task 3: Migrate `SecureIdVerificationDocumentsContext`
No build; no commit.
**File:** `submodules/PassportUI/Sources/SecureIdVerificationDocumentsContext.swift`
- [ ] **Step 1: Drop `import Postbox`**
Replace the import block at the top (lines 1–4):
```swift
import Foundation
import Postbox
import TelegramCore
import SwiftSignalKit
```
with:
```swift
import Foundation
import TelegramCore
import SwiftSignalKit
```
Only `Postbox` is removed. The three remaining imports stay.
- [ ] **Step 2: Replace stored properties**
Find the `final class SecureIdVerificationDocumentsContext` block (starting around line 18). Replace lines 20–21:
```swift
private let postbox: Postbox
private let network: Network
```
with:
```swift
private let engine: TelegramEngine
```
- [ ] **Step 3: Update the constructor**
Replace the `init` (lines 26–31):
```swift
init(postbox: Postbox, network: Network, context: SecureIdAccessContext, update: @escaping (Int64, SecureIdVerificationLocalDocumentState) -> Void) {
self.postbox = postbox
self.network = network
self.context = context
self.update = update
}
```
with:
```swift
init(engine: TelegramEngine, context: SecureIdAccessContext, update: @escaping (Int64, SecureIdVerificationLocalDocumentState) -> Void) {
self.engine = engine
self.context = context
self.update = update
}
```
- [ ] **Step 4: Update the `uploadSecureIdFile` call inside `stateUpdated`**
Find line 43, which currently reads:
```swift
disposable.set((uploadSecureIdFile(context: self.context, postbox: self.postbox, network: self.network, resource: info.resource)
```
Replace with:
```swift
disposable.set((uploadSecureIdFile(context: self.context, engine: self.engine, resource: EngineMediaResource(info.resource))
```
Two changes:
- `postbox: self.postbox, network: self.network` → `engine: self.engine`.
- `resource: info.resource` → `resource: EngineMediaResource(info.resource)`.
No other line in this file changes. The `DocumentContext` inner class is untouched. The `stateUpdated` method's outer structure is untouched.
---
## Task 4: Update the instantiation site
No build; no commit.
**File:** `submodules/PassportUI/Sources/SecureIdDocumentFormControllerNode.swift`
- [ ] **Step 1: Update line 2172**
Find line 2172, which currently reads:
```swift
self.uploadContext = SecureIdVerificationDocumentsContext(postbox: self.context.account.postbox, network: self.context.account.network, context: self.secureIdContext, update: { id, state in
```
Replace with:
```swift
self.uploadContext = SecureIdVerificationDocumentsContext(engine: self.context.engine, context: self.secureIdContext, update: { id, state in
```
Two removed arguments (`postbox:`, `network:`) collapse into one new argument (`engine:`). The closure body inside `update: { id, state in ... }` is unchanged.
No other line in this file changes. The file continues to `import Postbox` for unrelated reasons — this is expected, do not remove.
---
## Task 5: Full build and commit C1
- [ ] **Step 1: Run the full project build**
Run the build command from the header. Expected: clean success.
Typical failure modes and fixes (do them inline — do not split):
- **"cannot convert value of type 'Postbox' to expected argument type 'TelegramEngine'"** — a call site was missed. Re-grep both `uploadSecureIdFile(` and `SecureIdVerificationDocumentsContext(` across the repo.
- **"cannot convert value of type 'MediaResource' to expected argument type 'EngineMediaResource'"** — Task 3 Step 4's `EngineMediaResource(info.resource)` wrap was missed.
- **"use of unresolved identifier 'Network'"** or **"use of unresolved identifier 'Postbox'"** inside `SecureIdVerificationDocumentsContext.swift`** — Tasks 3 Steps 2–3 or 4 weren't fully applied.
- **"missing argument for parameter 'engine'"** — the Task 4 call site wasn't updated.
Re-run the build after each fix.
- [ ] **Step 2: Stage the three files**
```bash
git add \
submodules/TelegramCore/Sources/TelegramEngine/SecureId/UploadSecureIdFile.swift \
submodules/PassportUI/Sources/SecureIdVerificationDocumentsContext.swift \
submodules/PassportUI/Sources/SecureIdDocumentFormControllerNode.swift
```
- [ ] **Step 3: Verify diff scope**
```bash
git diff --staged --stat
```
Expected: exactly 3 files staged. Approximate line changes:
- `UploadSecureIdFile.swift`: ~3 lines (signature + 2 body sites).
- `SecureIdVerificationDocumentsContext.swift`: ~8 lines (1 import removed, stored props, constructor, call site).
- `SecureIdDocumentFormControllerNode.swift`: 1 line.
- [ ] **Step 4: Commit C1**
```bash
git commit -m "$(cat <<'EOF'
SecureId: migrate uploadSecureIdFile + context to TelegramEngine
uploadSecureIdFile's public signature now takes engine: TelegramEngine
and resource: EngineMediaResource instead of raw postbox: Postbox +
network: Network + MediaResource. The function body accesses raw
Postbox types via engine.account.postbox / engine.account.network
(internal Postbox-facing layer stays raw per CLAUDE.md).
SecureIdVerificationDocumentsContext refactored in lockstep: stores
engine: TelegramEngine instead of raw postbox + network, drops
import Postbox. The one instantiation site in
SecureIdDocumentFormControllerNode updates to pass engine:
self.context.engine.
Wave-5 of the Postbox -> TelegramEngine refactor; completes the last
explicitly-named future-wave candidate.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 5: Verify branch state**
```bash
git log --oneline master..HEAD
```
Expected (newest at top):
- `<sha> SecureId: migrate uploadSecureIdFile + context to TelegramEngine`
- `b7a1a5dfb0 docs(spec): wave-5 uploadSecureIdFile facade + SecureId context migration`
---
## Task 6: Update CLAUDE.md tally and commit C2
- [ ] **Step 1: Add `SecureIdVerificationDocumentsContext` to the Postbox-free tally**
Open `CLAUDE.md`. Find the "Modules currently free of `import Postbox` (running tally)" section. Add `- SecureIdVerificationDocumentsContext (wave 5)` as the last bullet in the list, immediately after `- SaveToCameraRoll (wave 3)`:
```markdown
- `MapResourceToAvatarSizes` (wave 2)
- `SaveToCameraRoll` (wave 3)
- `SecureIdVerificationDocumentsContext` (wave 5)
```
- [ ] **Step 2: Add a "Wave 5 outcome" subsection**
Still in `CLAUDE.md`, find the "Wave 4 outcome (2026-04-18)" block. Insert a new "Wave 5 outcome" subsection **after** Wave 4 and **before** "Modules currently free of `import Postbox`":
```markdown
### Wave 5 outcome (2026-04-18)
Completes the last explicitly-named future-wave candidate from the wave-2 final review.
`uploadSecureIdFile(context: SecureIdAccessContext, postbox: Postbox, network: Network, resource: MediaResource)` migrated in place to `(context:, engine: TelegramEngine, resource: EngineMediaResource)`. Function body accesses raw Postbox types via `engine.account.postbox` / `engine.account.network` (internal Postbox-facing layer stays raw per the standing rule).
1 consumer submodule fully de-Postboxed: `SecureIdVerificationDocumentsContext` (PassportUI/Sources). Signature changed from `(postbox: Postbox, network: Network, context: SecureIdAccessContext, update: ...)` to `(engine: TelegramEngine, context: SecureIdAccessContext, update: ...)`; stored props collapsed into a single `engine: TelegramEngine` field. One instantiation site updated in the same commit.
After this wave, the "Known future-wave candidates" list contains only the 4 permanently-blocked classes conforming to `TelegramMediaResource`.
Plan: `docs/superpowers/plans/2026-04-18-postbox-to-telegramengine-wave-5.md`
```
- [ ] **Step 3: Remove the `uploadSecureIdFile` bullet from "Known future-wave candidates"**
Still in `CLAUDE.md`, find the "Known future-wave candidates" list. Delete this bullet entirely:
```markdown
- `submodules/TelegramCore/Sources/TelegramEngine/SecureId/UploadSecureIdFile.swift: public func uploadSecureIdFile(…, postbox: Postbox, …, resource: MediaResource)` — rule-2-sensitive (umbrella-type leak). Needs a paired wave with its caller(s).
```
Do not touch the remaining bullet about permanently-blocked classes.
- [ ] **Step 4: Commit C2**
```bash
git add CLAUDE.md
git commit -m "$(cat <<'EOF'
CLAUDE.md: record wave-5 outcome
Adds SecureIdVerificationDocumentsContext to the Postbox-free module
tally, documents the uploadSecureIdFile facade migration, and removes
the uploadSecureIdFile bullet from "Known future-wave candidates".
After this wave, the candidate list contains only the 4 permanently-
blocked TelegramMediaResource-conforming classes.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 5: Verify final branch state**
```bash
git log --oneline master..HEAD
```
Expected:
- `<sha> CLAUDE.md: record wave-5 outcome`
- `<sha> SecureId: migrate uploadSecureIdFile + context to TelegramEngine`
- `b7a1a5dfb0 docs(spec): wave-5 uploadSecureIdFile facade + SecureId context migration`
---
## Success criteria
- `uploadSecureIdFile`'s public signature references neither `Postbox`, `Network`, nor `MediaResource`.
- `SecureIdVerificationDocumentsContext.swift` does not contain `import Postbox`.
- Full build succeeds in `debug_sim_arm64`.
- `grep -l "import Postbox" submodules/PassportUI/Sources/SecureIdVerificationDocumentsContext.swift` returns no match.
- `CLAUDE.md`'s "Known future-wave candidates" list no longer mentions `uploadSecureIdFile`; the Postbox-free running tally includes `SecureIdVerificationDocumentsContext (wave 5)`.
- Branch `refactor/postbox-to-engine-wave-5` contains 3 commits above `master`: 1 doc (spec) + 1 code (C1) + 1 tally (C2).

374
docs/superpowers/plans/2026-04-19-postbox-to-telegramengine-wave-6.md
View file

@ -1,374 +0,0 @@
# Postbox → TelegramEngine Wave 6 Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Speculatively drop `import Postbox` from every consumer file where a plain `^import Postbox$` line appears, run a full project build, restore the import on files that fail to compile, iterate up to 3 times, commit surviving drops as one atomic commit. Then land a CLAUDE.md update with the outcome and permanent methodology guidance.
**Architecture:** Two commits on branch `refactor/postbox-to-engine-wave-6`. C1 is the atomic batch deletion whose diff is N single-line removals (build-verified). C2 is a docs update that (a) records the outcome and (b) codifies the sweep methodology under "Wave-selection guidance" so future sweeps can be triggered directly. The project build is the safety net — anything that compiles after restoration is definitionally safe.
**Tech Stack:** Swift / Bazel. No unit tests — verification is a full project build.
**Spec:** [docs/superpowers/specs/2026-04-19-postbox-to-telegramengine-wave-6-design.md](docs/superpowers/specs/2026-04-19-postbox-to-telegramengine-wave-6-design.md)
**Build command** (use for every "full build" step):
```bash
source ~/.zshrc 2>/dev/null; PATH=/opt/homebrew/opt/ruby/bin:`gem environment gemdir`/bin:$PATH python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber 1 --configuration debug_sim_arm64
```
For background execution (recommended given build length), use `run_in_background: true` from the controller session. Do not let a subagent spawn the build — when the subagent returns the process orphans. The controller owns every build invocation in this wave.
---
## Task 1: Generate and record the candidate list
Read-only setup. No code changes yet.
- [ ] **Step 1: Generate the candidate list**
```bash
grep -rl "^import Postbox$" submodules --include="*.swift" \
| grep -vE "/(TelegramCore|Postbox|TelegramApi)/" \
| sort > /tmp/wave-6-candidates.txt
wc -l /tmp/wave-6-candidates.txt
```
Expected: a count somewhere between 100 and 400. Record the exact number — call it `N_candidates`. If the count is outside that range, stop and investigate: either the grep is too narrow (missing `@_exported` etc. ought to be rare) or too broad (accidentally matching TelegramCore).
- [ ] **Step 2: Snapshot baseline**
The snapshot is implicit: every candidate file is at branch HEAD, so `git checkout -- <file>` always restores the pre-sweep content. Verify the working tree is clean:
```bash
git status --short | grep -v '^??' | grep -v sourcekit-bazel-bsp
```
Expected: empty output. (The `sourcekit-bazel-bsp` submodule shows as modified across the whole repo; that's pre-existing and orthogonal.) If there are any other unstaged changes, commit or stash them before proceeding.
- [ ] **Step 3: Confirm branch and HEAD**
```bash
git branch --show-current
git log --oneline -3
```
Expected:
- current branch: `refactor/postbox-to-engine-wave-6`
- top commit: the wave-6 spec commit.
---
## Task 2: Speculative drop pass
Mutates all candidate files. No commit yet.
- [ ] **Step 1: Drop `import Postbox` from every candidate**
```bash
while IFS= read -r f; do
/usr/bin/sed -i '' '/^import Postbox$/d' "$f"
done < /tmp/wave-6-candidates.txt
```
macOS `sed` requires the `''` after `-i` (BSD flavor).
- [ ] **Step 2: Verify every candidate had exactly one line removed**
```bash
git diff --stat | wc -l
```
Expected: `N_candidates + 1` (one line per file in `--stat` output, plus the summary line).
```bash
git diff --stat | awk '{print $3}' | grep -v deletion | head -5
```
Expected: each shown entry is `1` (one insertion, zero counted since all are single-line deletes). If any file shows more than 1 line changed, something went wrong — investigate.
- [ ] **Step 3: Confirm no `@_exported` lines were accidentally touched**
```bash
grep -r "@_exported import Postbox" submodules --include="*.swift" | head -5
```
If this returns results, those lines must still be intact — verify. The regex used in Step 1 only matches bare `^import Postbox$`, so `@_exported import Postbox` is untouched. This step is a sanity check.
---
## Task 3: Iteration 1 — first build, parse errors, restore failing files
- [ ] **Step 1: Run the full project build (iteration 1)**
Run the build command from the header. Expected: many errors — this is by design. Capture stderr to the build output file.
Watch the tail of the output file for either `INFO: Build completed successfully` (rare: means zero imports were needed) or a cascade of compile errors (expected).
- [ ] **Step 2: Extract failing files from the build output**
```bash
BUILD_OUT=/private/tmp/claude-501/-Users-ali-build-telegram-telegram-ios/5d9b3268-5c9f-45fc-bd4e-87cac5361498/tasks/<task-id>.output
grep -E "^submodules/.*\.swift:[0-9]+:[0-9]+: error:" "$BUILD_OUT" \
| awk -F: '{print $1}' \
| sort -u > /tmp/wave-6-failing.txt
wc -l /tmp/wave-6-failing.txt
```
The task-id comes from the background Bash tool's output file. Substitute the actual `/private/tmp/claude-501/.../<task-id>.output` path.
Sanity-check the content:
```bash
head -3 /tmp/wave-6-failing.txt
```
Every line should be a path under `submodules/` that appears in `/tmp/wave-6-candidates.txt`. If any line is from `TelegramCore`, `Postbox`, or `TelegramApi`, the sweep has cascaded beyond the candidate set — halt and investigate.
- [ ] **Step 3: Validate error types**
```bash
grep -E "^submodules/.*\.swift:[0-9]+:[0-9]+: error:" "$BUILD_OUT" \
| head -10
```
Expected error patterns:
- `cannot find type 'X' in scope`
- `use of unresolved identifier 'X'`
- `cannot find 'X' in scope`
- `reference to invalid associated type 'X' of type 'Y'` (occasional)
If you see `no such module 'Postbox'` or errors unrelated to missing Postbox symbols (e.g., codesign failures, Bazel graph errors), halt and investigate — those are not the sweep's signal.
- [ ] **Step 4: Restore `import Postbox` on failing files**
```bash
while IFS= read -r f; do
git checkout -- "$f"
done < /tmp/wave-6-failing.txt
```
- [ ] **Step 5: Verify restoration**
```bash
git diff --stat | wc -l
```
Expected: `N_candidates - N_failing + 1` lines in `--stat` output (one per still-modified file plus summary). The count should be lower than Task 2 Step 2's count by exactly `N_failing`.
---
## Task 4: Iteration 2 — rebuild, parse new errors, restore
- [ ] **Step 1: Run the full project build (iteration 2)**
Run the build command again. Expected: ideally clean success. If errors persist, it's because restoring some files in iteration 1 removed a symbol that another file (still in the candidate set with import dropped) needed transitively via that symbol's module-level re-export.
Watch for `INFO: Build completed successfully`. If found, proceed to Task 6 (skipping Task 5). If errors persist, continue with Step 2.
- [ ] **Step 2: Extract failing files**
```bash
BUILD_OUT=/private/tmp/claude-501/-Users-ali-build-telegram-telegram-ios/5d9b3268-5c9f-45fc-bd4e-87cac5361498/tasks/<task-id-2>.output
grep -E "^submodules/.*\.swift:[0-9]+:[0-9]+: error:" "$BUILD_OUT" \
| awk -F: '{print $1}' \
| sort -u > /tmp/wave-6-failing-2.txt
wc -l /tmp/wave-6-failing-2.txt
```
- [ ] **Step 3: Restore**
```bash
while IFS= read -r f; do
git checkout -- "$f"
done < /tmp/wave-6-failing-2.txt
```
- [ ] **Step 4: Decision point**
If `wc -l /tmp/wave-6-failing-2.txt` is 0, the iteration-2 rebuild actually succeeded — proceed to Task 6. If it's greater than 0, proceed to Task 5 for iteration 3.
---
## Task 5: Iteration 3 — final rebuild
- [ ] **Step 1: Run the full project build (iteration 3)**
Run the build command again. If this iteration does not complete successfully, the sweep has failed the stability test.
- [ ] **Step 2: Clean-success check**
Expected: `INFO: Build completed successfully`.
If successful, proceed to Task 6.
If a third iteration of errors appears, **abandon the wave**:
```bash
git checkout -- .
git status --short
```
Working tree should now be clean (modulo the pre-existing sourcekit-bazel-bsp submodule marker). Do not commit. Skip Task 6. Jump straight to an updated Task 7 that records the failed attempt in CLAUDE.md instead of a success outcome, and document what kind of errors surfaced so a future attempt can plan around them.
---
## Task 6: Commit C1 — build-verified batch drop
- [ ] **Step 1: Compute the final count**
```bash
git diff --stat | tail -1
```
Expected: something like ` N files changed, 0 insertions(+), N deletions(-)` where N is the number of files that survived the sweep. Record this count as `N_dropped`.
- [ ] **Step 2: Spot-check a few diffs**
```bash
git diff | grep -E "^-import Postbox$" | wc -l
```
Expected: `N_dropped` (every surviving diff is a single-line `-import Postbox` removal).
```bash
git diff | grep -E "^\+" | grep -v "^+++" | head
```
Expected: no output. (The sweep only removes lines; it never adds any.)
- [ ] **Step 3: Stage all changes**
```bash
git add -u
```
`-u` stages only files that are already tracked and modified. No need to enumerate each file — the sweep touched many and they're all known to git.
- [ ] **Step 4: Commit**
```bash
N_DROPPED=$(git diff --staged --stat | tail -1 | awk '{print $1}')
git commit -m "$(cat <<EOF
Drop unused import Postbox from ${N_DROPPED} consumer files
Build-verified speculative drop: removed the import line from every
consumer submodule file where it appeared, rebuilt the full project,
and restored the import on the files that needed it. The commit
contains only survivors — every file here compiles cleanly without
import Postbox.
Methodology documented in CLAUDE.md (wave-selection guidance).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 5: Verify branch state**
```bash
git log --oneline master..HEAD
```
Expected:
- `<sha> Drop unused import Postbox from N consumer files`
- `816e7699ec docs(spec): wave-6 unused import Postbox batch sweep`
---
## Task 7: CLAUDE.md — record outcome and add permanent sweep methodology
- [ ] **Step 1: Add Wave 6 outcome subsection**
Open `CLAUDE.md`. Find the "Wave 5 outcome (2026-04-19)" block. Insert a new "Wave 6 outcome (2026-04-19)" subsection immediately after Wave 5 and before "Modules currently free of `import Postbox`":
```markdown
### Wave 6 outcome (2026-04-19)
First unused-import sweep. Ran the speculative-drop + build-verify methodology (see "Unused-import sweeps" under Wave-selection guidance): dropped `import Postbox` from every consumer file where a plain `^import Postbox$` appeared (out of ~N_CANDIDATES candidates), rebuilt, restored the import on failures, iterated. N_DROPPED drops survived.
No behavior change; zero facade migrations in this wave. Running tally updated for any modules whose last `import Postbox`-bearing file was swept (see the per-module list below).
Plan: `docs/superpowers/plans/2026-04-19-postbox-to-telegramengine-wave-6.md`
```
Replace `N_CANDIDATES` and `N_DROPPED` with the actual numbers from Task 1 Step 1 and Task 6 Step 1. If the wave was abandoned (see Task 5 Step 2), replace the outcome text with a failed-attempt description instead: what iteration the sweep stalled at and what error category.
- [ ] **Step 2: Add permanent "Unused-import sweeps" subsection under Wave-selection guidance**
Still in `CLAUDE.md`, find the "Wave-selection guidance" block. Insert the following new subsection at the end of that block (immediately before "### Wave 1 outcome"):
```markdown
**Unused-import sweeps are a valid wave shape.** After a round of facade migrations, consumer files accumulate `import Postbox` lines whose last semantic use was removed. Periodically sweep these:
1. `grep -rl "^import Postbox$" submodules --include="*.swift" | grep -vE "/(TelegramCore|Postbox|TelegramApi)/"` generates the candidate list.
2. `sed -i '' '/^import Postbox$/d' <file>` (BSD sed) speculatively drops the import from every candidate.
3. Run the full project build. Swift compile errors (`<file>:<line>:<col>: error: cannot find type 'X'`) identify files that need the import restored via `git checkout -- <file>`.
4. Rebuild. Iterate up to 3 times. Only restore files from the candidate set — if errors surface in `TelegramCore`, `Postbox`, or `TelegramApi`, halt and investigate (cascading breakage).
5. Commit the surviving drops as one atomic commit.
Re-run this after every 2–3 facade-migration waves. First run: wave 6.
```
- [ ] **Step 3: Update "Modules currently free of `import Postbox`" tally**
For each module in `submodules/` that has **no** remaining `import Postbox` after this wave, add a bullet under "Modules currently free of `import Postbox` (running tally)". Determine this list with:
```bash
for d in submodules/*/; do
mod=$(basename "$d")
if [ -d "$d/Sources" ]; then
count=$(grep -rlE "^(@_exported )?import Postbox" "$d/Sources" --include="*.swift" 2>/dev/null | wc -l)
if [ "$count" -eq 0 ]; then
# Check this module isn't already in CLAUDE.md's tally
if ! grep -qF "\`$mod\`" CLAUDE.md; then
echo "$mod"
fi
fi
fi
done
```
Each printed module becomes a new bullet like `- \`<ModuleName>\` (wave 6)` in the list.
If the output is empty, no new module-level additions — individual file drops across multiple mixed modules aren't tally-eligible. That's fine, the Wave-6 outcome subsection still records the raw count.
- [ ] **Step 4: Commit**
```bash
git add CLAUDE.md
git commit -m "$(cat <<'EOF'
CLAUDE.md: record wave-6 outcome and unused-import-sweep methodology
Adds the wave-6 outcome subsection with the candidate/drop counts,
documents the speculative-drop + build-verify methodology as
permanent guidance under wave-selection so future waves can re-run
the sweep directly, and updates the Postbox-free running tally for
any modules whose last import Postbox file was swept in this wave.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 5: Verify final branch state**
```bash
git log --oneline master..HEAD
```
Expected (newest first):
- `<sha> CLAUDE.md: record wave-6 outcome and unused-import-sweep methodology`
- `<sha> Drop unused import Postbox from N consumer files`
- `816e7699ec docs(spec): wave-6 unused import Postbox batch sweep`
---
## Success criteria
- At least one `import Postbox` line has been removed from at least one consumer file, build-verified.
- Full build succeeds in `debug_sim_arm64`.
- `CLAUDE.md` has a "Wave 6 outcome (2026-04-19)" subsection with actual numeric results.
- `CLAUDE.md`'s "Wave-selection guidance" section has a new permanent "Unused-import sweeps" bullet list that describes the methodology for future re-runs.
- `CLAUDE.md`'s "Modules currently free of `import Postbox`" running tally includes any newly-fully-clean modules (if any).
- Branch `refactor/postbox-to-engine-wave-6` contains 3 commits above `master`: 1 doc (spec) + 1 code (C1 batch drop) + 1 tally (C2).

539
docs/superpowers/plans/2026-04-20-decrypt-match-python-port.md
View file

@ -1,539 +0,0 @@
# Pure-Python port of fastlane match `decrypt.rb` — Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Replace the Ruby-based fastlane match decryption (`build-system/decrypt.rb` shelled from `BuildConfiguration.py:110`) with a self-contained Python 3 implementation using only the standard library.
**Architecture:** Rewrite `build-system/Make/DecryptMatch.py` from scratch as a pure-Python AES-256 implementation. Covers V1 (CBC via `EVP_BytesToKey` with MD5→SHA256 fallback) and V2 (GCM with PBKDF2-derived key/iv/AAD + auth tag). `BuildConfiguration.py` calls the existing `decrypt_match_data(source, destination, password)` entry point directly instead of shelling out to Ruby. `decrypt.rb` is deleted.
**Tech Stack:** Python 3 stdlib only — `hashlib` (MD5 / SHA256 / PBKDF2-HMAC), `base64`.
---
## File structure
- **Rewrite (not edit):** `build-system/Make/DecryptMatch.py` — new file replacing the broken placeholder. Single module containing: AES-256 primitives, `EVP_BytesToKey`, CBC decrypt, GCM decrypt (with GHASH + CTR), `MatchDataEncryption` dispatcher, `decrypt_match_data` public entry, `__main__` CLI.
- **Modify:** `build-system/Make/BuildConfiguration.py:103-118` — swap `os.system('ruby …')` for a direct Python call.
- **Delete:** `build-system/decrypt.rb`.
---
## Task 1: Rewrite `build-system/Make/DecryptMatch.py`
**Files:**
- Modify (rewrite): `build-system/Make/DecryptMatch.py`
- [ ] **Step 1.1: Replace the file contents entirely**
Overwrite `build-system/Make/DecryptMatch.py` with the following. This is the full file — no other changes to this module in later tasks.
```python
import base64
import hashlib
# FIPS-197 AES S-box and inverse S-box.
_SBOX = bytes.fromhex(
"637c777bf26b6fc53001672bfed7ab76"
"ca82c97dfa5947f0add4a2af9ca472c0"
"b7fd9326363ff7cc34a5e5f171d83115"
"04c723c31896059a071280e2eb27b275"
"09832c1a1b6e5aa0523bd6b329e32f84"
"53d100ed20fcb15b6acbbe394a4c58cf"
"d0efaafb434d338545f9027f503c9fa8"
"51a3408f929d38f5bcb6da2110fff3d2"
"cd0c13ec5f974417c4a77e3d645d1973"
"60814fdc222a908846eeb814de5e0bdb"
"e0323a0a4906245cc2d3ac629195e479"
"e7c8376d8dd54ea96c56f4ea657aae08"
"ba78252e1ca6b4c6e8dd741f4bbd8b8a"
"703eb5664803f60e613557b986c11d9e"
"e1f8981169d98e949b1e87e9ce5528df"
"8ca1890dbfe6426841992d0fb054bb16"
)
_INV_SBOX = bytes.fromhex(
"52096ad53036a538bf40a39e81f3d7fb"
"7ce339829b2fff87348e4344c4dee9cb"
"547b9432a6c2233dee4c950b42fac34e"
"082ea16628d924b2765ba2496d8bd125"
"72f8f66486689816d4a45ccc5d65b692"
"6c704850fdedb9da5e154657a78d9d84"
"90d8ab008cbcd30af7e45805b8b34506"
"d02c1e8fca3f0f02c1afbd0301138a6b"
"3a9111414f67dcea97f2cfcef0b4e673"
"96ac7422e7ad3585e2f937e81c75df6e"
"47f11a711d29c5896fb7620eaa18be1b"
"fc563e4bc6d279209adbc0fe78cd5af4"
"1fdda8338807c731b11210592780ec5f"
"60517fa919b54a0d2de57a9f93c99cef"
"a0e03b4dae2af5b0c8ebbb3c83539961"
"172b047eba77d626e169146355210c7d"
)
_RCON = bytes.fromhex("01020408102040801b36")
def _xtime(a):
return (((a << 1) ^ 0x1b) & 0xff) if (a & 0x80) else (a << 1)
def _gf_mul(a, b):
r = 0
for _ in range(8):
if b & 1:
r ^= a
b >>= 1
a = _xtime(a)
return r
def _key_expansion_256(key):
# AES-256: Nk=8, Nr=14, total 4 * (Nr + 1) = 60 words = 240 bytes.
assert len(key) == 32
w = bytearray(240)
w[:32] = key
i = 32
while i < 240:
t = bytearray(w[i - 4:i])
if i % 32 == 0:
t = bytearray([t[1], t[2], t[3], t[0]])
for j in range(4):
t[j] = _SBOX[t[j]]
t[0] ^= _RCON[i // 32 - 1]
elif i % 32 == 16:
for j in range(4):
t[j] = _SBOX[t[j]]
for j in range(4):
w[i + j] = w[i - 32 + j] ^ t[j]
i += 4
return [bytes(w[r * 16:(r + 1) * 16]) for r in range(15)]
def _add_round_key(state, rk):
return bytes(s ^ k for s, k in zip(state, rk))
def _sub_bytes(state):
return bytes(_SBOX[b] for b in state)
def _inv_sub_bytes(state):
return bytes(_INV_SBOX[b] for b in state)
# Column-major state: state[r + 4 * c], r = 0..3 (row), c = 0..3 (column).
def _shift_rows(state):
s = bytearray(state)
s[1], s[5], s[9], s[13] = s[5], s[9], s[13], s[1]
s[2], s[6], s[10], s[14] = s[10], s[14], s[2], s[6]
s[3], s[7], s[11], s[15] = s[15], s[3], s[7], s[11]
return bytes(s)
def _inv_shift_rows(state):
s = bytearray(state)
s[1], s[5], s[9], s[13] = s[13], s[1], s[5], s[9]
s[2], s[6], s[10], s[14] = s[10], s[14], s[2], s[6]
s[3], s[7], s[11], s[15] = s[7], s[11], s[15], s[3]
return bytes(s)
def _mix_columns(state):
s = bytearray(16)
for c in range(4):
a0, a1, a2, a3 = state[4 * c], state[4 * c + 1], state[4 * c + 2], state[4 * c + 3]
s[4 * c] = _xtime(a0) ^ (_xtime(a1) ^ a1) ^ a2 ^ a3
s[4 * c + 1] = a0 ^ _xtime(a1) ^ (_xtime(a2) ^ a2) ^ a3
s[4 * c + 2] = a0 ^ a1 ^ _xtime(a2) ^ (_xtime(a3) ^ a3)
s[4 * c + 3] = (_xtime(a0) ^ a0) ^ a1 ^ a2 ^ _xtime(a3)
return bytes(s)
def _inv_mix_columns(state):
s = bytearray(16)
for c in range(4):
a0, a1, a2, a3 = state[4 * c], state[4 * c + 1], state[4 * c + 2], state[4 * c + 3]
s[4 * c] = _gf_mul(a0, 0x0e) ^ _gf_mul(a1, 0x0b) ^ _gf_mul(a2, 0x0d) ^ _gf_mul(a3, 0x09)
s[4 * c + 1] = _gf_mul(a0, 0x09) ^ _gf_mul(a1, 0x0e) ^ _gf_mul(a2, 0x0b) ^ _gf_mul(a3, 0x0d)
s[4 * c + 2] = _gf_mul(a0, 0x0d) ^ _gf_mul(a1, 0x09) ^ _gf_mul(a2, 0x0e) ^ _gf_mul(a3, 0x0b)
s[4 * c + 3] = _gf_mul(a0, 0x0b) ^ _gf_mul(a1, 0x0d) ^ _gf_mul(a2, 0x09) ^ _gf_mul(a3, 0x0e)
return bytes(s)
def _aes_encrypt_block(block, round_keys):
state = _add_round_key(block, round_keys[0])
for r in range(1, 14):
state = _sub_bytes(state)
state = _shift_rows(state)
state = _mix_columns(state)
state = _add_round_key(state, round_keys[r])
state = _sub_bytes(state)
state = _shift_rows(state)
state = _add_round_key(state, round_keys[14])
return state
def _aes_decrypt_block(block, round_keys):
state = _add_round_key(block, round_keys[14])
for r in range(13, 0, -1):
state = _inv_shift_rows(state)
state = _inv_sub_bytes(state)
state = _add_round_key(state, round_keys[r])
state = _inv_mix_columns(state)
state = _inv_shift_rows(state)
state = _inv_sub_bytes(state)
state = _add_round_key(state, round_keys[0])
return state
def _evp_bytes_to_key(password, salt, hash_name, key_len=32, iv_len=16):
# OpenSSL EVP_BytesToKey with count=1, matching Ruby's
# Cipher#pkcs5_keyivgen(password, salt, 1, hash).
if isinstance(password, str):
password = password.encode('utf-8')
required = key_len + iv_len
material = b""
prev = b""
while len(material) < required:
h = hashlib.new(hash_name)
h.update(prev + password + salt)
prev = h.digest()
material += prev
return material[:key_len], material[key_len:key_len + iv_len]
def _aes_cbc_decrypt(ciphertext, key, iv):
if len(ciphertext) == 0 or len(ciphertext) % 16 != 0:
raise ValueError("V1 ciphertext length must be a non-zero multiple of 16")
round_keys = _key_expansion_256(key)
out = bytearray()
prev = iv
for i in range(0, len(ciphertext), 16):
block = ciphertext[i:i + 16]
decrypted = _aes_decrypt_block(block, round_keys)
out.extend(bytes(d ^ p for d, p in zip(decrypted, prev)))
prev = block
pad = out[-1]
if pad < 1 or pad > 16 or not all(b == pad for b in out[-pad:]):
raise ValueError("V1 PKCS#7 padding check failed")
return bytes(out[:-pad])
def _ghash(h_bytes, data):
# GHASH over GF(2^128) with reduction polynomial x^128 + x^7 + x^2 + x + 1,
# using GCM's bit-reversed convention (top-bit-first when encoded as bytes).
h = int.from_bytes(h_bytes, 'big')
y = 0
reduction = 0xe1 << 120
for i in range(0, len(data), 16):
block = data[i:i + 16].ljust(16, b"\x00")
y ^= int.from_bytes(block, 'big')
z = 0
v = y
for bit in range(127, -1, -1):
if (h >> bit) & 1:
z ^= v
if v & 1:
v = (v >> 1) ^ reduction
else:
v >>= 1
y = z
return y.to_bytes(16, 'big')
def _aes_gcm_decrypt(ciphertext, key, iv, aad, auth_tag):
if len(iv) != 12:
raise ValueError("V2 requires a 96-bit IV")
round_keys = _key_expansion_256(key)
H = _aes_encrypt_block(b"\x00" * 16, round_keys)
j0 = iv + b"\x00\x00\x00\x01"
plaintext = bytearray()
j0_int = int.from_bytes(j0, 'big')
mask32 = (1 << 32) - 1
counter_high = j0_int & ~mask32
counter_low = j0_int & mask32
n_blocks = (len(ciphertext) + 15) // 16
for i in range(n_blocks):
counter_low = (counter_low + 1) & mask32
ctr_bytes = (counter_high | counter_low).to_bytes(16, 'big')
keystream = _aes_encrypt_block(ctr_bytes, round_keys)
block = ciphertext[i * 16:(i + 1) * 16]
plaintext.extend(bytes(c ^ k for c, k in zip(block, keystream[:len(block)])))
aad_pad = b"\x00" * ((16 - len(aad) % 16) % 16)
ct_pad = b"\x00" * ((16 - len(ciphertext) % 16) % 16)
length_block = (len(aad) * 8).to_bytes(8, 'big') + (len(ciphertext) * 8).to_bytes(8, 'big')
s = _ghash(H, aad + aad_pad + ciphertext + ct_pad + length_block)
e_j0 = _aes_encrypt_block(j0, round_keys)
computed_tag = bytes(a ^ b for a, b in zip(s, e_j0))
if computed_tag != auth_tag:
raise ValueError("V2 GCM auth tag mismatch")
return bytes(plaintext)
_V1_PREFIX = b"Salted__"
_V2_PREFIX = b"match_encrypted_v2__"
def _decrypt_stored(stored_data, password):
if stored_data.startswith(_V2_PREFIX):
salt = stored_data[20:28]
auth_tag = stored_data[28:44]
ciphertext = stored_data[44:]
material = hashlib.pbkdf2_hmac(
'sha256',
password.encode('utf-8'),
salt,
10_000,
dklen=32 + 12 + 24,
)
key = material[0:32]
iv = material[32:44]
aad = material[44:68]
return _aes_gcm_decrypt(ciphertext, key, iv, aad, auth_tag)
if stored_data.startswith(_V1_PREFIX):
salt = stored_data[8:16]
ciphertext = stored_data[16:]
try:
key, iv = _evp_bytes_to_key(password, salt, 'md5', 32, 16)
return _aes_cbc_decrypt(ciphertext, key, iv)
except Exception:
key, iv = _evp_bytes_to_key(password, salt, 'sha256', 32, 16)
return _aes_cbc_decrypt(ciphertext, key, iv)
raise ValueError("Unrecognized fastlane match payload (missing V1 'Salted__' or V2 'match_encrypted_v2__' prefix)")
def decrypt_match_data(source_path: str, destination_path: str, password: str):
with open(source_path, 'rb') as f:
raw = f.read()
stored_data = base64.b64decode(raw)
decrypted = _decrypt_stored(stored_data, password)
with open(destination_path, 'wb') as f:
f.write(decrypted)
if __name__ == '__main__':
import sys
if len(sys.argv) != 4:
print('Usage: DecryptMatch.py <password> <source_path> <destination_path>')
sys.exit(1)
decrypt_match_data(source_path=sys.argv[2], destination_path=sys.argv[3], password=sys.argv[1])
```
---
## Task 2: Smoke-test the AES-256 block primitive (FIPS-197 Appendix C.3)
**Files:**
- No changes. One-liner shell command to validate the just-written primitive.
- [ ] **Step 2.1: Run the FIPS-197 C.3 known-answer test**
```bash
cd /Users/isaac/build/telegram/telegram-ios
python3 -c "
import sys
sys.path.insert(0, 'build-system/Make')
from DecryptMatch import _key_expansion_256, _aes_encrypt_block, _aes_decrypt_block
key = bytes.fromhex('000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f')
pt = bytes.fromhex('00112233445566778899aabbccddeeff')
expected = bytes.fromhex('8ea2b7ca516745bfeafc49904b496089')
rks = _key_expansion_256(key)
assert _aes_encrypt_block(pt, rks) == expected, 'encrypt failed'
assert _aes_decrypt_block(expected, rks) == pt, 'decrypt failed'
print('AES-256 FIPS-197 C.3 OK')
"
```
Expected output: `AES-256 FIPS-197 C.3 OK`. If this fails, the AES primitive is broken — re-read Task 1's code and fix before proceeding.
---
## Task 3: Validate V2 decryption on real encrypted files
**Files:**
- No changes. Decrypt real samples with the new Python and verify each output is a cryptographically-valid Apple-signed artifact.
**Success criteria:** the decrypted `.mobileprovision` files verify under `openssl smime -verify` and parse as valid plists. A CMS signature covers every byte of the payload, so successful verification is equivalent to bit-exact decryption — any wrong byte anywhere would break the signature. This is a stronger check than diffing against another implementation, and it matches what `BuildConfiguration.copy_profiles_from_directory` does on every profile in the real build, so passing here means the port is production-ready.
The encrypted repo is at `~/build/telegram/telegram-ios/build-input/configuration-repository-workdir/encrypted/profiles/development/`. Repo password: `sluchainost` (per the hard-coded value in the file Task 1 replaced).
> NOTE: Do not attempt a byte-for-byte comparison against `ruby build-system/decrypt.rb`. Ruby's OpenSSL binding on macOS LibreSSL 3.3.6 fails on `cipher.auth_data=` with `couldn't set additional authenticated data`, so the legacy script cannot decrypt V2 at all on current macOS. (This is likely why the build accumulated a broken aspirational Python port in the first place.) Signature verification of the Python output is the authoritative check.
- [ ] **Step 3.1: Decrypt one sample file**
```bash
cd /Users/isaac/build/telegram/telegram-ios
SAMPLE=~/build/telegram/telegram-ios/build-input/configuration-repository-workdir/encrypted/profiles/development/Development_org.telegram.TelegramInternal.BroadcastUpload.mobileprovision
python3 build-system/Make/DecryptMatch.py sluchainost "$SAMPLE" /tmp/match-py.bin
shasum -a 256 /tmp/match-py.bin
```
Expected: `match-py.bin` is non-empty; a sha256 is printed.
- [ ] **Step 3.2: Verify the output is a valid Apple-signed provisioning profile**
```bash
openssl smime -inform der -verify -noverify -in /tmp/match-py.bin | plutil -lint -
```
Expected: `openssl smime` prints `Verification successful` (or similar; exit code 0 is what matters), and `plutil` reports `OK`. Either failure means the decryption is corrupt — STOP and report BLOCKED with the exact openssl/plutil output.
- [ ] **Step 3.3: Spot-check remaining V2 files decrypt without error**
```bash
cd /Users/isaac/build/telegram/telegram-ios
ENCRYPTED=~/build/telegram/telegram-ios/build-input/configuration-repository-workdir/encrypted/profiles/development
for f in "$ENCRYPTED"/*.mobileprovision; do
python3 build-system/Make/DecryptMatch.py sluchainost "$f" /tmp/match-check.bin \
&& openssl smime -inform der -verify -noverify -in /tmp/match-check.bin > /dev/null 2>&1 \
&& echo "OK $(basename "$f")" \
|| echo "FAIL $(basename "$f")"
done
```
Expected: every line starts with `OK`. Any `FAIL` line means that file's decryption is corrupt — STOP and report BLOCKED.
---
## Task 4: Commit the rewrite
**Files:**
- Commit `build-system/Make/DecryptMatch.py` only.
- [ ] **Step 4.1: Stage and commit**
```bash
cd /Users/isaac/build/telegram/telegram-ios
git add build-system/Make/DecryptMatch.py
git commit -m "$(cat <<'EOF'
DecryptMatch: pure-Python AES-256 port of decrypt.rb
Implements fastlane match V1 (AES-256-CBC via EVP_BytesToKey with
MD5 default and SHA256 fallback) and V2 (AES-256-GCM with PBKDF2-
derived key/IV/AAD + auth tag) using only Python stdlib. Validated
by decrypting every V2 .mobileprovision in the repo and confirming
each output verifies under openssl smime + plutil -lint as a valid
Apple-signed artifact.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
Expected: commit created cleanly.
---
## Task 5: Switch `BuildConfiguration.py` to the Python implementation and remove `decrypt.rb`
**Files:**
- Modify: `build-system/Make/BuildConfiguration.py:103-118`
- Delete: `build-system/decrypt.rb`
- [ ] **Step 5.1: Swap the call site**
Replace lines 103-118 of `build-system/Make/BuildConfiguration.py`:
```python
def decrypt_codesigning_directory_recursively(source_base_path, destination_base_path, password):
for file_name in os.listdir(source_base_path):
source_path = source_base_path + '/' + file_name
destination_path = destination_base_path + '/' + file_name
allowed_file_extensions = ['.mobileprovision', '.cer', '.p12']
if os.path.isfile(source_path) and any(source_path.endswith(ext) for ext in allowed_file_extensions):
#print('Decrypting {} to {} with {}'.format(source_path, destination_path, password))
os.system('ruby build-system/decrypt.rb "{password}" "{source_path}" "{destination_path}"'.format(
password=password,
source_path=source_path,
destination_path=destination_path
))
#decrypt_match_data(source_path, destination_path, password)
elif os.path.isdir(source_path):
os.makedirs(destination_path, exist_ok=True)
decrypt_codesigning_directory_recursively(source_path, destination_path, password)
```
with:
```python
def decrypt_codesigning_directory_recursively(source_base_path, destination_base_path, password):
for file_name in os.listdir(source_base_path):
source_path = source_base_path + '/' + file_name
destination_path = destination_base_path + '/' + file_name
allowed_file_extensions = ['.mobileprovision', '.cer', '.p12']
if os.path.isfile(source_path) and any(source_path.endswith(ext) for ext in allowed_file_extensions):
decrypt_match_data(source_path, destination_path, password)
elif os.path.isdir(source_path):
os.makedirs(destination_path, exist_ok=True)
decrypt_codesigning_directory_recursively(source_path, destination_path, password)
```
- [ ] **Step 5.2: Delete the Ruby script**
```bash
cd /Users/isaac/build/telegram/telegram-ios
git rm build-system/decrypt.rb
```
- [ ] **Step 5.3: Commit**
```bash
cd /Users/isaac/build/telegram/telegram-ios
git add build-system/Make/BuildConfiguration.py
git commit -m "$(cat <<'EOF'
BuildConfiguration: use Python DecryptMatch, drop Ruby decrypt.rb
Swap the os.system('ruby build-system/decrypt.rb ...') shell-out for
a direct decrypt_match_data() call, and delete the now-unused Ruby
script. The iOS build no longer depends on a Ruby interpreter.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
Expected: commit created cleanly; `git status` shows a clean tree.
---
## Task 6: End-to-end verification with `generateProject`
**Files:**
- No changes.
- [ ] **Step 6.1: Wipe the previously-decrypted directory so the build re-decrypts fresh**
```bash
cd /Users/isaac/build/telegram/telegram-ios
rm -rf ~/build/telegram/telegram-ios/build-input/configuration-repository-workdir/decrypted
```
Expected: directory removed. If it did not exist, that's also fine.
- [ ] **Step 6.2: Run the user-supplied `generateProject` command**
```bash
cd /Users/isaac/build/telegram/telegram-ios
source ~/.zshrc 2>/dev/null
python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/build/telegram/telegram-bazel-cache \
generateProject \
--configurationPath ~/build/telegram/telegram-internal-tools/PrivateData/build-configurations/enterprise-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent
```
Expected: the command runs through project generation. The decryption step is silent on success (per `BuildConfiguration.py:decrypt_codesigning_directory_recursively`). Any decryption failure would surface downstream in `copy_profiles_from_directory` when `openssl smime -verify` chokes on a corrupted `.mobileprovision`, so a clean run proves the port is working end-to-end.
If the command fails with a decryption-related error, revert the two commits (`git revert HEAD~1..HEAD`) and debug; otherwise the migration is complete.
- [ ] **Step 6.3: Spot-check the generated decrypted directory**
```bash
ls ~/build/telegram/telegram-ios/build-input/configuration-repository-workdir/decrypted/profiles/development/
```
Expected: a populated list of `.mobileprovision` files, matching the list in the encrypted sibling directory.

194
docs/superpowers/plans/2026-04-20-postbox-to-telegramengine-wave-10.md
View file

@ -1,194 +0,0 @@
# Postbox → TelegramEngine Wave 10 Implementation Plan
> **For agentic workers:** This plan was executed in a single session; steps below are a post-hoc record of the work landed, not a to-do list.
**Goal:** Finish the `StorageUsageScreen` consumer-module de-Postbox work started in wave 8 and continued in wave 9 by eliminating the last `import Postbox` in the module: `StorageFileListPanelComponent.swift`'s `Icon.media(Media, TelegramMediaImageRepresentation)` enum case.
**Architecture:** Replace the heterogeneous-protocol `Icon.media(Media, ...)` case with two concrete-type cases `.mediaFile(TelegramMediaFile, ...)` and `.mediaImage(TelegramMediaImage, ...)`. The split is lossless because the two construction sites already knew the concrete subtype (`imageIconValue = .media(file, representation)` vs `.media(image, representation)`), and the one consumer binding site immediately downcasted via `as? TelegramMediaFile` / `as? TelegramMediaImage` to pick which `setSignal(...)` to call. Auto-split the switch body over the two new cases; no downcast needed. Also replaces a placeholder `PeerId(namespace:..., id:...)` construction in the `measureItem` layout-measurement instance with `component.context.account.peerId` (a real, already-available `EnginePeer.Id`).
**Tech Stack:** Swift / Bazel. No unit tests.
**Build command:**
```bash
source ~/.zshrc 2>/dev/null; PATH=/opt/homebrew/opt/ruby/bin:`gem environment gemdir`/bin:$PATH python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber 1 --configuration debug_sim_arm64 --continueOnError
```
---
## Scope
**In scope:**
- `StorageFileListPanelComponent.swift`'s `Icon` enum: replace `case media(Media, TelegramMediaImageRepresentation)` with two concrete-type cases.
- Equatable rewrite: switch-over-tuple `(lhs, rhs)` pattern with id-based equality per concrete type (`lFile.fileId == rFile.fileId`, `lImage.imageId == rImage.imageId`).
- Binding rewrite at the `if case let .media(media, representation)` site (former line 448): lift `representation` via a compound `case let .mediaFile(_, representation), let .mediaImage(_, representation):` pattern, then inner switch-over-`component.icon` selects `setSignal` flavor.
- Construction rewrite at two `imageIconValue = .media(...)` sites: use the concrete case name (`.mediaFile`, `.mediaImage`).
- Placeholder `PeerId(namespace:..., id:...)` at former line 1062 (in the `measureItem` layout-measurement instance): replace with `component.context.account.peerId`.
- Remove `import Postbox` from `StorageFileListPanelComponent.swift`.
**Out of scope:**
- None. This is the last file in the `StorageUsageScreen` module that imports Postbox; after this wave, the module is fully Postbox-free.
---
## Tasks
### Task 1: Split `Icon.media` into two concrete cases
**Files:**
- Modify: `submodules/TelegramUI/Components/StorageUsageScreen/Sources/StorageFileListPanelComponent.swift` (former 103–135).
Before:
```swift
enum Icon: Equatable {
case fileExtension(String)
case media(Media, TelegramMediaImageRepresentation)
case audio
static func ==(lhs: Icon, rhs: Icon) -> Bool {
switch lhs {
case let .fileExtension(value):
if case .fileExtension(value) = rhs { return true } else { return false }
case let .media(media, representation):
if case let .media(rhsMedia, rhsRepresentation) = rhs {
if media.id != rhsMedia.id { return false }
if representation != rhsRepresentation { return false }
return true
} else { return false }
case .audio:
if case .audio = rhs { return true } else { return false }
}
}
}
```
After:
```swift
enum Icon: Equatable {
case fileExtension(String)
case mediaFile(TelegramMediaFile, TelegramMediaImageRepresentation)
case mediaImage(TelegramMediaImage, TelegramMediaImageRepresentation)
case audio
static func ==(lhs: Icon, rhs: Icon) -> Bool {
switch (lhs, rhs) {
case let (.fileExtension(l), .fileExtension(r)):
return l == r
case let (.mediaFile(lFile, lRepresentation), .mediaFile(rFile, rRepresentation)):
return lFile.fileId == rFile.fileId && lRepresentation == rRepresentation
case let (.mediaImage(lImage, lRepresentation), .mediaImage(rImage, rRepresentation)):
return lImage.imageId == rImage.imageId && lRepresentation == rRepresentation
case (.audio, .audio):
return true
default:
return false
}
}
}
```
### Task 2: Rewrite the binding site
**Files:**
- Modify: `submodules/TelegramUI/Components/StorageUsageScreen/Sources/StorageFileListPanelComponent.swift` (former 448–500).
Before, the block started with `if case let .media(media, representation) = component.icon { ... }` then inside did `if let file = media as? TelegramMediaFile { ... } else if let image = media as? TelegramMediaImage { ... }`.
After, use a compound case-binding pattern at the entry (both cases have the same `representation` type, so the pattern works) and an inner switch for the `setSignal` branch:
```swift
let mediaRepresentation: TelegramMediaImageRepresentation?
switch component.icon {
case let .mediaFile(_, representation), let .mediaImage(_, representation):
mediaRepresentation = representation
default:
mediaRepresentation = nil
}
if let representation = mediaRepresentation {
// ... setup iconImageNode as before ...
if resetImage {
switch component.icon {
case let .mediaFile(file, _):
iconImageNode.setSignal(chatWebpageSnippetFile(
account: component.context.account,
userLocation: .peer(component.messageId.peerId),
mediaReference: FileMediaReference.standalone(media: file).abstract,
representation: representation,
automaticFetch: false
))
case let .mediaImage(image, _):
iconImageNode.setSignal(mediaGridMessagePhoto(
account: component.context.account,
userLocation: .peer(component.messageId.peerId),
photoReference: ImageMediaReference.standalone(media: image),
automaticFetch: false
))
default:
break
}
}
// ... frame + asyncLayout + apply as before ...
}
```
### Task 3: Update the two construction sites
**Files:**
- Modify: `submodules/TelegramUI/Components/StorageUsageScreen/Sources/StorageFileListPanelComponent.swift` (former 985 and 992).
`imageIconValue = .media(file, representation)` → `.mediaFile(file, representation)` (for `TelegramMediaFile` branch).
`imageIconValue = .media(image, representation)` → `.mediaImage(image, representation)` (for `TelegramMediaImage` branch).
### Task 4: Replace the placeholder `PeerId(...)` construction
**Files:**
- Modify: `submodules/TelegramUI/Components/StorageUsageScreen/Sources/StorageFileListPanelComponent.swift` (former 1062).
The `measureItem` layout-measurement instance uses a fully-zero placeholder peer id:
```swift
messageId: EngineMessage.Id(peerId: PeerId(namespace: PeerId.Namespace._internalFromInt32Value(0), id: PeerId.Id._internalFromInt64Value(0)), namespace: 0, id: 0),
```
Naming `PeerId`, `PeerId.Namespace`, `PeerId.Id` all require `import Postbox` (these are raw Postbox types, not TelegramCore typealiases). Replace with `component.context.account.peerId`, a real `EnginePeer.Id` already in scope:
```swift
messageId: EngineMessage.Id(peerId: component.context.account.peerId, namespace: 0, id: 0),
```
Semantically equivalent for the measurement use case — `messageId` is used downstream only for `.peerId` extraction in the image-fetch userLocation and for Equatable comparison; the measurement instance is standalone and not compared. The `id: 0, namespace: 0` part stays; those are plain `Int32`, nothing Postbox-specific.
Caught by second-pass build failure `cannot find 'PeerId' in scope` after dropping `import Postbox`.
### Task 5: Drop `import Postbox`
**Files:**
- Modify: `submodules/TelegramUI/Components/StorageUsageScreen/Sources/StorageFileListPanelComponent.swift` (former line 14).
Remove the `import Postbox` line.
### Task 6: Full project build
Expected green after Tasks 4 and 5. The first build attempt surfaced the `PeerId` issue; Task 4's fix addressed it.
### Task 7: Commit
Single wave-10 atomic commit. CLAUDE.md gets a wave-10 outcome section; the "Modules currently free of `import Postbox`" tally gains `StorageUsageScreen` (the module as a whole). Both files that previously imported Postbox in this module (`StorageUsageScreen.swift` from wave 9 and `StorageFileListPanelComponent.swift` from wave 10) are now Postbox-free.
---
## Outcome (2026-04-20)
Single atomic commit. Build verified green (27 actions, cached).
**`StorageUsageScreen` consumer module is now fully Postbox-free** — last file (`StorageFileListPanelComponent.swift`) landed in this wave; the other file (`StorageUsageScreen.swift`) landed in wave 9.
Net: 1 file changed, +22 / -29 lines (−7 simplification — the new switch-over-tuple Equatable is both terser and more idiomatic than the old three-way nested `switch` + `if case` pattern).
**Lessons:**
- **Heterogeneous-protocol enum cases are an easy de-Postbox win** when the protocol values already get downcast to a fixed small set of concrete subtypes. The compiler-enforced exhaustiveness of the split improves call-site safety (no silent `else` branch that forgot a subtype).
- **Placeholder `PeerId(...)` constructions in layout-measurement code are traps.** Common pattern in this codebase: a "dummy" component instance is constructed purely to run `.update(...)` and harvest the returned size. The dummy values (`messageId`, `peerId`) are not used for anything but type-filling, yet naming the types forces `import Postbox`. When de-Postboxing, look for `PeerId(namespace:...`/`MessageId(peerId:...` constructions with all-zero arguments and replace with any convenient real value already in scope (`context.account.peerId` works for peer-id placeholders).

95
docs/superpowers/plans/2026-04-20-postbox-to-telegramengine-wave-7.md
View file

@ -1,95 +0,0 @@
# Postbox → TelegramEngine Wave 7 Implementation Plan
> **For agentic workers:** This plan was executed in a single session; steps below are a post-hoc record of the work landed, not a to-do list.
**Goal:** Close out the remaining raw-Postbox leaks in `TelegramEngine.*` public facades surfaced by the wave-6 post-sweep scouting pass (2026-04-20). Six facade-signature migrations + one dead-facade deletion + consumer call-site bridging, landed as a single wave commit.
**Architecture:** Wave-2 shape scaled to seven facades at once: each facade signature changes in place from raw Postbox domain types (`Message`, `Peer`) to engine equivalents (`EngineMessage`, `EnginePeer`), with `_internal_*` implementations left raw per the standing "internal Postbox-facing stays raw" rule. Consumer call sites bridge at the facade boundary via `EngineMessage.init` / `._asMessage()` wrap/unwrap helpers or drop now-redundant wrapping.
**Tech Stack:** Swift / Bazel. No unit tests by repo policy — verification is a full project build.
**Build command:**
```bash
source ~/.zshrc 2>/dev/null; PATH=/opt/homebrew/opt/ruby/bin:`gem environment gemdir`/bin:$PATH python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber 1 --configuration debug_sim_arm64 --continueOnError
```
---
## Scope — candidate list
All seven items from the wave-6 post-sweep scouting pass:
1. `TelegramEngine.Messages.downloadMessage(messageId: MessageId) -> Signal<Message?, NoError>` → `(messageId: EngineMessage.Id) -> Signal<EngineMessage?, NoError>`. Callers: 1 (`ChatListSearchListPaneNode`).
2. `TelegramEngine.Messages.topPeerActiveLiveLocationMessages(peerId: PeerId) -> Signal<(Peer?, [Message]), NoError>` → `(peerId: EnginePeer.Id) -> Signal<(EnginePeer?, [EngineMessage]), NoError>`. Callers: 2 (`LocationViewControllerNode`, `LiveLocationSummaryManager`).
3. `TelegramEngine.Messages.getSynchronizeAutosaveItemOperations()` — dead facade (sole caller `StoreDownloadedMedia.swift:298` uses `_internal_*` directly). Deleted.
4. `TelegramEngine.Peers.updatedRemotePeer(peer: PeerReference) -> Signal<Peer, UpdatedRemotePeerError>` → `Signal<EnginePeer, UpdatedRemotePeerError>`. `PeerReference` param kept (no `EnginePeer.Reference` alias today). Callers: 1 (`ChannelAdminsController`, `ignoreValues` so no caller change needed).
5. `TelegramEngine.Resources.renderStorageUsageStatsMessages(…existingMessages: [EngineMessage.Id: Message]) -> Signal<[EngineMessage.Id: Message], NoError>` → `[EngineMessage.Id: EngineMessage]` on both sides. Callers: 1 (`StorageUsageScreen`).
6–8. `TelegramEngine.Resources.clearStorage(...)` overloads (three) — `[Message]` params → `[EngineMessage]`. Real external callers: 2 (`StorageUsageScreen`, two overloads). The third overload `clearStorage(messages:)` has no callers; migrated for overload-set consistency.
---
## Tasks
### Task 1: Migrate three `TelegramEngine.Messages` facades
**Files:**
- Modify: `submodules/TelegramCore/Sources/TelegramEngine/Messages/TelegramEngineMessages.swift` (3 facades)
- Modify: `submodules/ChatListUI/Sources/ChatListSearchListPaneNode.swift` (drop redundant `.flatMap(EngineMessage.init)`)
- Modify: `submodules/LocationUI/Sources/LocationViewControllerNode.swift` (drop redundant `.map(EngineMessage.init)`)
- Modify: `submodules/LiveLocationManager/Sources/LiveLocationSummaryManager.swift` (drop redundant `EnginePeer(...)` / `EngineMessage(...)` wrappers)
**Changes:**
`downloadMessage` — wrap return `Message?` → `EngineMessage?` via `|> map { $0.flatMap(EngineMessage.init) }`. `_internal_downloadMessage` still takes `messageId: MessageId`, which is typealiased to `EngineMessage.Id`, so the param change is purely a rename at the public surface.
`topPeerActiveLiveLocationMessages` — wrap tuple return via `|> map { peer, messages -> (EnginePeer?, [EngineMessage]) in (peer.flatMap(EnginePeer.init), messages.map(EngineMessage.init)) }`.
`getSynchronizeAutosaveItemOperations` — deleted. The sole caller `StoreDownloadedMedia.swift:298` was already calling `_internal_getSynchronizeAutosaveItemOperations` directly (inside its own transaction block), so no caller update needed.
### Task 2: Migrate `TelegramEngine.Peers.updatedRemotePeer`
**Files:**
- Modify: `submodules/TelegramCore/Sources/TelegramEngine/Peers/TelegramEnginePeers.swift`
Append `|> map(EnginePeer.init)` to wrap the `Peer` result. `PeerReference` param stays. Single call site in `ChannelAdminsController.swift` uses `ignoreValues`, so no caller-side change.
### Task 3: Migrate four `TelegramEngine.Resources` facades
**Files:**
- Modify: `submodules/TelegramCore/Sources/TelegramEngine/Resources/TelegramEngineResources.swift` (4 facades)
- Modify: `submodules/TelegramUI/Components/StorageUsageScreen/Sources/StorageUsageScreen.swift` (3 call sites)
`renderStorageUsageStatsMessages` — unwrap `[EngineMessage.Id: EngineMessage]` input via `.mapValues { $0._asMessage() }`, wrap raw result via `.mapValues(EngineMessage.init)`. Caller bridges the other direction at its single call site (`.mapValues(EngineMessage.init)` on the input `existingMessages`, `.mapValues { $0._asMessage() }` on the mapped result).
`clearStorage(peerId:categories:includeMessages:excludeMessages:)` / `clearStorage(peerIds:includeMessages:excludeMessages:)` / `clearStorage(messages:)` — unwrap `[EngineMessage]` params via `.map { $0._asMessage() }` before forwarding to `_internal_clearStorage`. Callers bridge `[Message]` locals with `.map(EngineMessage.init)` at the facade call site.
Call-site changes in `StorageUsageScreen` are intentionally minimal: the file's `AggregatedData` type keeps `[MessageId: Message]` / `[Message]` internally, with bridging applied only at the four facade-call points. A full-consumer-module migration to `EngineMessage` is out of scope for this wave (would require changing ~30 sites plus the item types in `StorageFileListPanelComponent`; a future "StorageUsageScreen full de-Postbox" wave could land that).
### Task 4: Full project build
Run the build command above with `--continueOnError`. Expected: clean build (no errors or warnings introduced). One full build covers all facades since they're in TelegramCore and rebuilding TelegramCore re-verifies every consumer.
### Task 5: Commit
Single wave-7 atomic commit covering the 8 modified files and the CLAUDE.md outcome update.
---
## Outcome (2026-04-20)
All seven candidates landed. Single atomic commit. Build verified green (`bazel-bin/Telegram/Telegram.ipa` produced; 5854 total actions, 1009 executed).
- 3 `TelegramEngine.Messages` facades migrated (1 rewrite, 1 rewrite, 1 deletion)
- 1 `TelegramEngine.Peers` facade migrated
- 4 `TelegramEngine.Resources` facades migrated (1 dict, 3 overloads)
- 5 consumer files updated: `ChatListSearchListPaneNode`, `LocationViewControllerNode`, `LiveLocationSummaryManager`, `StorageUsageScreen`, CLAUDE.md
No modules became Postbox-free in this wave (all five touched consumers still import Postbox for unrelated reasons — `StorageUsageScreen` especially, which still has 43 raw `Message` / `MessageId` references outside the facade boundary).
**Lesson recorded:** when a facade's consumer file uses the raw Postbox type extensively outside the facade boundary (e.g. `StorageUsageScreen` with its `[MessageId: Message]` dict stored in a helper class and threaded through ~30 sites), bridging at the facade call site is the correct scope. Full-consumer-module migration is its own separate wave, not a side-effect of facade migration.
**Next-wave candidates.** The sum of the scouting pass's 8 candidates has been closed. No new `TelegramEngine.*` public facades with raw `Postbox`/`Account`/`MediaBox`/`Peer`/`Message`/`MediaResource` leaks remain. Future-wave focus shifts to:
1. Full-consumer-module migrations (e.g. `StorageUsageScreen` — drop `AggregatedData`'s raw-Postbox storage types, drop `import Postbox`).
2. Another speculative unused-import sweep pass like wave 6, to catch imports that became unused after waves 4–7.

103
docs/superpowers/plans/2026-04-20-postbox-to-telegramengine-wave-8.md
View file

@ -1,103 +0,0 @@
# Postbox → TelegramEngine Wave 8 Implementation Plan
> **For agentic workers:** This plan was executed in a single session; steps below are a post-hoc record of the work landed, not a to-do list.
**Goal:** `StorageUsageScreen` consumer-module migration — drop all raw `Message` domain types from the screen's internal storage and public peer-panel item types, and eliminate the wave-7 facade-boundary bridging. Scope is narrower than a full de-Postbox of the module: direct `postbox.combinedView` / `postbox.transaction` sites for `AccountSpecificCacheStorageSettings` observation are left for a future wave.
**Architecture:** Two files modified. `StorageFileListPanelComponent.Item.message` and `StorageUsageScreen`'s `AggregatedData` + `RenderResult` + `SelectionState` internal types are migrated from raw `Message`/`[Message]`/`[MessageId: Message]` to `EngineMessage`/`[EngineMessage]`/`[EngineMessage.Id: EngineMessage]`. The two external APIs that still take raw `Message` (`OpenChatMessageParams.message`, `chatMediaListPreviewControllerData(message:)`) are called with `engineMessage._asMessage()` at the call site.
**Tech Stack:** Swift / Bazel. No unit tests by repo policy — verification is a full project build.
**Build command:**
```bash
source ~/.zshrc 2>/dev/null; PATH=/opt/homebrew/opt/ruby/bin:`gem environment gemdir`/bin:$PATH python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber 1 --configuration debug_sim_arm64 --continueOnError
```
---
## Scope
**In scope:**
- `StorageFileListPanelComponent.Item.message: Message` → `EngineMessage` (the item type co-located with the panel component).
- `StorageUsageScreen.Component.SelectionState.togglePeer(id:availableMessages: [EngineMessage.Id: Message])` → `[EngineMessage.Id: EngineMessage]`.
- `StorageUsageScreen.Component.AggregatedData.messages: [MessageId: Message]` → `[EngineMessage.Id: EngineMessage]`.
- `AggregatedData.clearIncludeMessages: [Message]` / `.clearExcludeMessages: [Message]` → `[EngineMessage]` (plus the corresponding local vars in `AggregatedData.updateSelected...`).
- `AggregatedData.init(..., messages: [MessageId: Message])` → `[EngineMessage.Id: EngineMessage]`.
- `StorageUsageScreen.Component.RenderResult.messages: [MessageId: Message]` → `[EngineMessage.Id: EngineMessage]`.
- `openMessage(message: Message)` → `openMessage(message: EngineMessage)`.
- Drop the now-redundant wave-7 facade-boundary bridging (`.mapValues(EngineMessage.init)` on `existingMessages`, `.mapValues { $0._asMessage() }` on the facade's engineMessages output, `.map(EngineMessage.init)` on the two `clearStorage` call sites, `._asMessage()` on `item.message` inside the `AggregatedData.updateSelected...` loop, and `EngineMessage(message)` inside the `result.imageItems.append(...)` site).
**Out of scope — left for a future wave:**
- Direct postbox usage for `AccountSpecificCacheStorageSettings` observation: `StorageUsageScreen.swift:1047-1062` and `3131-3185`. Blocks `import Postbox` removal. Requires engine equivalents for `PostboxViewKey.preferences` / `PreferencesView` observation and for `transaction.getPeer` / `transaction.getPeerCachedData` — likely an `EngineData`-subscription based rewrite plus peer-category classification via already-existing engine APIs.
- `StorageFileListPanelComponent`'s `Icon.media(Media, TelegramMediaImageRepresentation)` enum case. Holds either `TelegramMediaFile` or `TelegramMediaImage` (always one of these two TelegramCore types per `imageIconValue = .media(file, ...)` and `.media(image, ...)` construction sites). Could be split into `.mediaFile(TelegramMediaFile, ...)` / `.mediaImage(TelegramMediaImage, ...)` to eliminate the raw `Media` protocol dependency; out of scope as it's unrelated to Message-type migration.
---
## Tasks
### Task 1: Migrate `StorageFileListPanelComponent.Item.message`
**Files:**
- Modify: `submodules/TelegramUI/Components/StorageUsageScreen/Sources/StorageFileListPanelComponent.swift` — `Item.message` type and `init(message:)` param.
No other changes inside the file. Internal usage (`item.message.id`, `item.message.timestamp`, `item.message.media`) already works on `EngineMessage` — `EngineMessage.media` returns `[Media]` (raw), so the `as? TelegramMediaFile` / `as? TelegramMediaImage` downcasts inside the `for media in item.message.media` loop still compile.
### Task 2: Migrate `StorageUsageScreen` internal storage types
**Files:**
- Modify: `submodules/TelegramUI/Components/StorageUsageScreen/Sources/StorageUsageScreen.swift`
Change:
- `SelectionState.togglePeer(availableMessages: [EngineMessage.Id: Message])` → `[EngineMessage.Id: EngineMessage]`. Body only uses `messageId.peerId` so no body change required.
- `AggregatedData.messages` / `.clearIncludeMessages` / `.clearExcludeMessages` type declarations and the init param.
- The selected-messages accumulation loop inside `AggregatedData` (the block running from the photo/video/file/music category branches): drop `item.message._asMessage()` in the two photo/video branches (`imageItems` holds EngineMessage items, so `._asMessage()` was the EngineMessage→Message unwrap to fit the old `[Message]` local); `item.message` in the file/music branches now passes through since Item.message is EngineMessage.
- `RenderResult.messages` type.
### Task 3: Drop wave-7 facade-boundary bridging
At `StorageUsageScreen.swift:2397` the `renderStorageUsageStatsMessages` call previously wrapped input via `(self.aggregatedData?.messages ?? [:]).mapValues(EngineMessage.init)` and unwrapped output via `.mapValues { $0._asMessage() }`. With `AggregatedData.messages` and `RenderResult.messages` now EngineMessage-typed, both bridges vanish: the call just passes `self.aggregatedData?.messages ?? [:]` directly and assigns the result to `result.messages` unchanged.
At the two `clearStorage` call sites in `StorageUsageScreen.swift` (inside `clearSelected(...)`): `aggregatedData.clearIncludeMessages.map(EngineMessage.init)` → `aggregatedData.clearIncludeMessages` (same for `excludeMessages`), plus the local `includeMessages: [Message]` / `excludeMessages: [Message]` vars become `[EngineMessage]`.
At the `RenderResult`-building loop (post-`renderStorageUsageStatsMessages`), `StorageMediaGridPanelComponent.Item(message: EngineMessage(message), ...)` → `message: message` since `message` is already `EngineMessage`.
### Task 4: Migrate `openMessage` + external-API unwraps
`openMessage(message: Message)` → `openMessage(message: EngineMessage)`. Two external APIs receive raw `Message`: pass `message._asMessage()` to `OpenChatMessageParams(message:)` inside `openMessage`, and to `chatMediaListPreviewControllerData(message:)` inside `messageGaleryContextAction`. Also drop the one-line `let foundGalleryMessage: Message? = message` + `guard let galleryMessage = foundGalleryMessage` dance inside `openMessage` — it's a no-op wrap preserved from an older version.
### Task 5: Full project build
Expected clean (cached — 30 seconds on an incremental build; ~60s from a cold start since wave 7).
### Task 6: Commit
Single wave-8 atomic commit.
---
## Outcome (2026-04-20)
Single atomic commit landing the migration. Build verified green (59s incremental, 27 actions). Net -5 lines (simplification, as expected — most changes are type swaps and a handful of redundant wraps/unwraps removed).
Two files modified:
| File | Δ |
|---|---|
| `submodules/TelegramUI/Components/StorageUsageScreen/Sources/StorageUsageScreen.swift` | +33 / -44 |
| `submodules/TelegramUI/Components/StorageUsageScreen/Sources/StorageFileListPanelComponent.swift` | +3 / -3 |
**Module did NOT become Postbox-free.** Both files retain `import Postbox` for the out-of-scope sites listed above. Drop-candidacy inventory in `StorageUsageScreen.swift`:
- 1047–1062: preferences-view observation of `AccountSpecificCacheStorageSettings` via `postbox.combinedView` + `PreferencesView`.
- 3131–3185: second preferences-view observation + `postbox.transaction { transaction in ... transaction.getPeer / transaction.getPeerCachedData as? CachedGroupData / CachedChannelData ... }` for classifying peer-storage-timeout exceptions.
And in `StorageFileListPanelComponent.swift`:
- 105: `Icon.media(Media, TelegramMediaImageRepresentation)` enum case.
Future wave targets either the preferences-view observation sites (substantial — `EngineData`-subscription rewrite + peer-category classification via engine APIs) or the `Icon.media` split (trivial — 3 sites to update).
Plan / record: `docs/superpowers/plans/2026-04-20-postbox-to-telegramengine-wave-8.md`.

162
docs/superpowers/plans/2026-04-20-postbox-to-telegramengine-wave-9.md
View file

@ -1,162 +0,0 @@
# Postbox → TelegramEngine Wave 9 Implementation Plan
> **For agentic workers:** This plan was executed in a single session; steps below are a post-hoc record of the work landed, not a to-do list.
**Goal:** Finish the `StorageUsageScreen` de-Postbox work started in wave 8 by rewriting the two remaining direct-postbox sites that observe `AccountSpecificCacheStorageSettings`, and drop `import Postbox` from `StorageUsageScreen.swift`.
**Architecture:** Replace `postbox.combinedView(keys: [.preferences(...)]) + PreferencesView` observation with `context.engine.data.subscribe(TelegramEngine.EngineData.Item.Configuration.ApplicationSpecificPreference(key:))`, which returns `PreferencesEntry?` and is then decoded the same way (`.get(AccountSpecificCacheStorageSettings.self)`). Replace the transaction-based per-peer classification (`transaction.getPeer` + `transaction.getPeerCachedData as? CachedGroupData/CachedChannelData`) with an `EngineDataMap` of `TelegramEngine.EngineData.Item.Peer.Peer.init(id:)` lookups producing `EnginePeer?` values that pattern-match on `.user` / `.legacyGroup` / `.channel(channel)` / `.secretChat`. The `FoundPeer(peer:subscribers:)` wrapper in the signal's element type is dropped entirely since downstream consumers (`peerExceptions.isEmpty`, `.count`, `.prefix(3).map { EnginePeer($0.peer.peer) }`) never read `subscribers`.
**Tech Stack:** Swift / Bazel. No unit tests.
**Build command:**
```bash
source ~/.zshrc 2>/dev/null; PATH=/opt/homebrew/opt/ruby/bin:`gem environment gemdir`/bin:$PATH python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber 1 --configuration debug_sim_arm64 --continueOnError
```
---
## Scope
Two direct-postbox site clusters rewritten in `StorageUsageScreen.swift`:
1. **Site 1 (former lines 1047–1087)** — `cacheSettingsExceptionCount` signal. Preserved its downstream `EngineDataMap` + `EnginePeer` per-category counting logic unchanged; only the preferences observation replaced.
2. **Site 2 (former lines 3131–3196)** — `peerExceptions` signal inside `openKeepMediaCategory`. Both the preferences observation AND the `postbox.transaction { transaction.getPeer / transaction.getPeerCachedData ... FoundPeer(...) }` block replaced. Signal element type changed from `[(peer: FoundPeer, value: Int32)]` to `[(peer: EnginePeer, value: Int32)]`; `FoundPeer` and the unread `subscribers` field dropped.
One consumer-side edit: `peerExceptions.prefix(3).map { EnginePeer($0.peer.peer) }` → `peerExceptions.prefix(3).map { $0.peer }` (at the `MultiplePeerAvatarsContextItem` construction).
One typealias fixup: `var mergedMedia: [MessageId: Int64]` → `[EngineMessage.Id: Int64]` (required once `import Postbox` is removed, since `MessageId` is the raw Postbox name, not a TelegramCore typealias).
`import Postbox` removed from `StorageUsageScreen.swift`.
---
## Tasks
### Task 1: Rewrite site 1 — cacheSettingsExceptionCount
**Files:**
- Modify: `submodules/TelegramUI/Components/StorageUsageScreen/Sources/StorageUsageScreen.swift` (former 1047–1058).
Replace the preferences observation header. The downstream `mapToSignal { ... EngineDataMap ... EnginePeer ... }` body is already Engine-only and unchanged.
Before:
```swift
let viewKey: PostboxViewKey = .preferences(keys: Set([PreferencesKeys.accountSpecificCacheStorageSettings]))
let cacheSettingsExceptionCount: Signal<[CacheStorageSettings.PeerStorageCategory: Int32], NoError> = component.context.account.postbox.combinedView(keys: [viewKey])
|> map { views -> AccountSpecificCacheStorageSettings in
let cacheSettings: AccountSpecificCacheStorageSettings
if let view = views.views[viewKey] as? PreferencesView, let value = view.values[PreferencesKeys.accountSpecificCacheStorageSettings]?.get(AccountSpecificCacheStorageSettings.self) {
cacheSettings = value
} else {
cacheSettings = AccountSpecificCacheStorageSettings.defaultSettings
}
return cacheSettings
}
|> distinctUntilChanged
|> mapToSignal { ... }
```
After:
```swift
let cacheSettingsExceptionCount: Signal<[CacheStorageSettings.PeerStorageCategory: Int32], NoError> = context.engine.data.subscribe(
TelegramEngine.EngineData.Item.Configuration.ApplicationSpecificPreference(key: PreferencesKeys.accountSpecificCacheStorageSettings)
)
|> map { preferencesEntry -> AccountSpecificCacheStorageSettings in
return preferencesEntry?.get(AccountSpecificCacheStorageSettings.self) ?? AccountSpecificCacheStorageSettings.defaultSettings
}
|> distinctUntilChanged
|> mapToSignal { ... }
```
### Task 2: Rewrite site 2 — peerExceptions
**Files:**
- Modify: `submodules/TelegramUI/Components/StorageUsageScreen/Sources/StorageUsageScreen.swift` (former 3131–3196).
Replace both the preferences observation (as in Task 1) AND the subsequent `mapToSignal { context.account.postbox.transaction { ... } }` block. Signal element type changes from `[(peer: FoundPeer, value: Int32)]` to `[(peer: EnginePeer, value: Int32)]`. `subscriberCount` is not preserved — it's computed but never read by downstream consumers.
After (showing the `peerExceptions` signal in full):
```swift
let peerExceptions: Signal<[(peer: EnginePeer, value: Int32)], NoError> = accountSpecificSettings
|> mapToSignal { accountSpecificSettings -> Signal<[(peer: EnginePeer, value: Int32)], NoError> in
return context.engine.data.get(
EngineDataMap(accountSpecificSettings.peerStorageTimeoutExceptions.map(\.key).map(TelegramEngine.EngineData.Item.Peer.Peer.init(id:)))
)
|> map { peers -> [(peer: EnginePeer, value: Int32)] in
var result: [(peer: EnginePeer, value: Int32)] = []
for item in accountSpecificSettings.peerStorageTimeoutExceptions {
guard let peer = peers[item.key] ?? nil else { continue }
let peerCategory: CacheStorageSettings.PeerStorageCategory
switch peer {
case .user, .secretChat:
peerCategory = .privateChats
case .legacyGroup:
peerCategory = .groups
case let .channel(channel):
if case .group = channel.info {
peerCategory = .groups
} else {
peerCategory = .channels
}
}
if peerCategory != mappedCategory { continue }
result.append((peer: peer, value: item.value))
}
return result.sorted(by: { lhs, rhs in
if lhs.value != rhs.value {
return lhs.value < rhs.value
}
return lhs.peer.debugDisplayTitle < rhs.peer.debugDisplayTitle
})
}
}
```
### Task 3: Update consumer of `peerExceptions`
**Files:**
- Modify: `submodules/TelegramUI/Components/StorageUsageScreen/Sources/StorageUsageScreen.swift` (former 3288).
`peerExceptions.prefix(3).map { EnginePeer($0.peer.peer) }` → `peerExceptions.prefix(3).map { $0.peer }`. The `MultiplePeerAvatarsContextItem(context:, peers: [EnginePeer], totalCount:, action:)` signature is unchanged — we simply drop the redundant `EnginePeer(...)` wrap because `$0.peer` is now already an `EnginePeer`.
### Task 4: Drop `import Postbox`
**Files:**
- Modify: `submodules/TelegramUI/Components/StorageUsageScreen/Sources/StorageUsageScreen.swift` (line 12).
Remove the `import Postbox` line.
### Task 5: Typealias fixup for `MessageId`
**Files:**
- Modify: `submodules/TelegramUI/Components/StorageUsageScreen/Sources/StorageUsageScreen.swift` (former 2397).
`var mergedMedia: [MessageId: Int64]` → `[EngineMessage.Id: Int64]`. `MessageId` is the raw Postbox type name; with `import Postbox` removed, the type must be named through the `EngineMessage.Id` typealias. Discovered by first-pass build failure `cannot find type 'MessageId' in scope`.
### Task 6: Full project build
Expected green. Incremental build: ~60s (cached), 27 actions.
### Task 7: Commit
Single wave-9 atomic commit. CLAUDE.md updates the wave 8 outcome's "future-wave candidates" note since this wave closes both of them. `StorageUsageScreen` (the module as a whole) now has `StorageUsageScreen.swift` Postbox-free; the module's `StorageFileListPanelComponent.swift` still imports Postbox because of the `Icon.media(Media, TelegramMediaImageRepresentation)` enum case (trivial future wave, as previously noted).
---
## Outcome (2026-04-20)
Single atomic commit. Build verified green (27 actions, ~60s incremental).
Net change: 1 file, +30 / -54 lines (-24 simplification).
Lessons:
- **`ApplicationSpecificPreference(key:)` is the general-purpose engine replacement** for any `postbox.combinedView(keys: [.preferences(keys: Set([key]))])` idiom. Takes a `ValueBoxKey`, returns `PreferencesEntry?`, decodes via `.get(T.self)`. Usable from any module that imports `TelegramCore` even without `import Postbox`, because the `ValueBoxKey`-typed input is obtained through a statically-named `PreferencesKeys.*` member (no `ValueBoxKey` identifier appears in the consumer).
- **`MessageId` is raw Postbox, not a TelegramCore typealias.** CLAUDE.md's "engine typealias cheat sheet" labels `PeerId`, `MessageId`, etc. as migration *targets*, not existing aliases. Files that drop `import Postbox` must rename these to `EngineMessage.Id` / `EnginePeer.Id`. Caught by the first-pass build failure.
- **Dead-code detection during rewrites.** The transaction block's `subscriberCount` computation and the `FoundPeer.subscribers` field it populated were never consumed downstream. The rewrite simply dropped them, shrinking the code further than a 1:1 rewrite would have.
`StorageUsageScreen.swift` is now Postbox-free. The `StorageUsageScreen` consumer module as a whole is still not fully Postbox-free because `StorageFileListPanelComponent.swift` retains `import Postbox` for its `Icon.media(Media, TelegramMediaImageRepresentation)` enum case (3 construction sites; trivial future wave splits into `.mediaFile(TelegramMediaFile, ...)` / `.mediaImage(TelegramMediaImage, ...)`).

1037
docs/superpowers/plans/2026-04-21-swifttl-layered-schema-generation.md
View file

File diff suppressed because it is too large Load diff

351
docs/superpowers/plans/2026-04-21-textstyleeditscreen-caret-tracking.md
View file

@ -1,351 +0,0 @@
# TextStyleEditScreen caret-tracking Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** On every text change inside `TextStyleEditScreen`, scroll the enclosing `ResizableSheetComponent` scroll view so the caret in the active `ListMultilineTextFieldItemComponent` stays visible ~24pt above the keyboard/bottom button area.
**Architecture:** Single-file change in `submodules/TelegramUI/Components/TextProcessingScreen/Sources/TextStyleEditScreen.swift`. Give each text field a `ListMultilineTextFieldItemComponent.Tag`; at the end of `TextStyleEditContentComponent.View.update(...)`, read `TextFieldComponent.AnimationHint` off the transition's userData; on a `.textChanged` hint, resolve the editing field, compute the caret rect via `UITextInput.caretRect(for:)`, walk `superview` to the enclosing `UIScrollView`, and adjust its `bounds.origin.y` using the direct-assign + additive-animate pattern from `ComposePollScreen.swift:2873-2895`.
**Tech Stack:** Swift, UIKit, Telegram's ComponentFlow (`ComponentView`, `ComponentTransition`, `TextFieldComponent.AnimationHint`), Bazel via `Make.py`. No unit tests exist in this project — verification is a full build + manual smoke test per `CLAUDE.md`.
**Reference spec:** `docs/superpowers/specs/2026-04-21-textstyleeditscreen-caret-tracking-design.md`.
**Reference precedent:** `submodules/TelegramUI/Components/ComposePollScreen/Sources/ComposePollScreen.swift:2733-2895` (field-bounds variant of this same pattern).
---
## File Structure
Only one file is touched:
- **Modify:** `submodules/TelegramUI/Components/TextProcessingScreen/Sources/TextStyleEditScreen.swift`
- Add two stored `ListMultilineTextFieldItemComponent.Tag` properties on `TextStyleEditContentComponent.View`.
- Thread those tags into the two existing `ListMultilineTextFieldItemComponent(...)` constructions inside `update(...)`.
- Add a private `recenterCaret(hintView:transition:)` method on `TextStyleEditContentComponent.View`.
- Call `recenterCaret` from the tail of `update(...)` when the transition carries a `.textChanged` `TextFieldComponent.AnimationHint`.
No other files are modified. Public API of `ResizableSheetComponent`, `ListMultilineTextFieldItemComponent`, and `TextFieldComponent` is used as-is.
---
## Task 1: Add field tags and wire them into the two text field constructors
**Files:**
- Modify: `submodules/TelegramUI/Components/TextProcessingScreen/Sources/TextStyleEditScreen.swift` (around lines 64-77, 277, 322)
- [ ] **Step 1: Add the two `Tag` stored properties to `TextStyleEditContentComponent.View`**
In `TextStyleEditScreen.swift`, locate the stored-property block at the top of `final class View: UIView` (lines 64-77). Below `private let linkOption = ComponentView<Empty>()` (line 76) add:
```swift
private let titleFieldTag = ListMultilineTextFieldItemComponent.Tag()
private let textFieldTag = ListMultilineTextFieldItemComponent.Tag()
```
Keep them above the `override init(frame: CGRect)` at line 78.
- [ ] **Step 2: Pass `self.titleFieldTag` into the title field constructor**
Locate the `ListMultilineTextFieldItemComponent(...)` construction for the title section (starts at line 260). Its last argument currently reads `tag: nil` (line 277). Change it to:
```swift
tag: self.titleFieldTag
```
- [ ] **Step 3: Pass `self.textFieldTag` into the prompt field constructor**
Locate the second `ListMultilineTextFieldItemComponent(...)` construction for the text section (starts at line 304). Its last argument currently reads `tag: nil` (line 322). Change it to:
```swift
tag: self.textFieldTag
```
- [ ] **Step 4: Verify the change compiles**
Run:
```bash
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 --configuration=debug_sim_arm64 \
--continueOnError
```
Expected: build succeeds (or the same pre-existing failures unrelated to `TextStyleEditScreen.swift`). A failure in `TextStyleEditScreen.swift` means the tag types or property names are wrong — fix before moving on.
- [ ] **Step 5: Do not commit yet** — tag wiring is inert without the recenter logic. Defer commit to Task 4.
---
## Task 2: Add the `recenterCaret` helper
**Files:**
- Modify: `submodules/TelegramUI/Components/TextProcessingScreen/Sources/TextStyleEditScreen.swift`
- [ ] **Step 1: Add the method on `TextStyleEditContentComponent.View`**
Inside `final class View: UIView` (the class that starts at line 64), directly **before** the `func update(component:availableSize:state:environment:transition:)` method (line 86), add this private method. It covers steps 1–6 from the design spec (locate field view → caret rect → scroll view → scroll view coordinates → visible region → adjust bounds).
```swift
private func recenterCaret(hintView: UIView, transition: ComponentTransition) {
var fieldView: ListMultilineTextFieldItemComponent.View?
var ancestor: UIView? = hintView
while let current = ancestor {
if let candidate = current as? ListMultilineTextFieldItemComponent.View {
fieldView = candidate
break
}
ancestor = current.superview
}
guard let fieldView else {
return
}
if !(fieldView.matches(tag: self.titleFieldTag) || fieldView.matches(tag: self.textFieldTag)) {
return
}
guard let inputTextView = fieldView.textFieldView?.inputTextView else {
return
}
let caretPosition = inputTextView.selectedTextRange?.end ?? inputTextView.endOfDocument
let caretRect = inputTextView.caretRect(for: caretPosition)
if caretRect.isNull || caretRect.isInfinite {
return
}
var scrollAncestor: UIView? = self.superview
var scrollView: UIScrollView?
while let current = scrollAncestor {
if let candidate = current as? UIScrollView {
scrollView = candidate
break
}
scrollAncestor = current.superview
}
guard let scrollView, let environment = self.environment else {
return
}
let caretInScroll = inputTextView.convert(caretRect, to: scrollView)
let bottomActionAreaHeight: CGFloat = 60.0
let caretTopInset: CGFloat = 24.0
let caretBottomInset: CGFloat = 24.0
let visibleTop = scrollView.bounds.minY + caretTopInset
let visibleBottom = scrollView.bounds.maxY - environment.inputHeight - bottomActionAreaHeight - caretBottomInset
let previousBounds = scrollView.bounds
var newBounds = previousBounds
if caretInScroll.maxY > visibleBottom {
newBounds.origin.y += (caretInScroll.maxY - visibleBottom)
} else if caretInScroll.minY < visibleTop {
newBounds.origin.y -= (visibleTop - caretInScroll.minY)
}
let maxOriginY = max(0.0, scrollView.contentSize.height - scrollView.bounds.height)
newBounds.origin.y = min(max(0.0, newBounds.origin.y), maxOriginY)
if newBounds != previousBounds {
scrollView.bounds = newBounds
if !transition.animation.isImmediate {
let offsetY = previousBounds.origin.y - newBounds.origin.y
transition.animateBoundsOrigin(view: scrollView, from: CGPoint(x: 0.0, y: offsetY), to: CGPoint(), additive: true)
}
}
}
```
Notes on key choices:
- `bottomActionAreaHeight: 60.0` = `52.0` (bottom item height — see `ResizableSheetComponent.swift:750`) + `8.0` gap above the button (matches `ResizableSheetComponent.swift:732`).
- `caretTopInset` / `caretBottomInset` (both `24.0`) provide the "small inset" biased positioning the user confirmed.
- The hint's view ancestor walk is used (rather than `self.titleFieldTag`'s / `self.textFieldTag`'s views directly) because the hint already carries the `TextFieldComponent.View` that actually fired the change — this is safer than guessing which of our two fields is editing when both may have briefly claimed focus.
- `transition.animateBoundsOrigin` is the proven pattern from `ComposePollScreen.swift:2891-2894`; `transition.animation.isImmediate` gating avoids an unnecessary animation when the transition is immediate.
- Silent bails on missing scroll view or text view keep the code robust against host refactors (they should never happen in normal operation).
- [ ] **Step 2: Verify compilation**
Re-run the build command from Task 1 Step 4. Expected: the method compiles cleanly. Common failure modes to watch for:
- `cannot find 'ListMultilineTextFieldItemComponent.View' in scope` → wrong type path; check the import and the class name in `ListMultilineTextFieldItemComponent.swift:196` (it is the nested `View` class of `ListMultilineTextFieldItemComponent`).
- `value of type 'TextFieldComponent.View' has no member 'inputTextView'` → the property is defined at `TextFieldComponent.swift:359`; ensure you're reading `fieldView.textFieldView?.inputTextView`, not reaching into private internals.
- `'ComponentTransition' has no member 'animateBoundsOrigin'` → this is a ComponentFlow method; grep confirms it exists and is used at `ComposePollScreen.swift:2893`. If missing, the import line (`import ComponentFlow`) at file top is the place to check.
- [ ] **Step 3: Do not commit yet** — the helper is unreferenced and unused. Defer commit to Task 4.
---
## Task 3: Hook up the `.textChanged` trigger in `update(...)`
**Files:**
- Modify: `submodules/TelegramUI/Components/TextProcessingScreen/Sources/TextStyleEditScreen.swift`
- [ ] **Step 1: Add the trigger at the tail of `update(...)`**
At the end of `func update(component:availableSize:state:environment:transition:)` on `TextStyleEditContentComponent.View`, locate lines 455-460:
```swift
contentHeight += 104.0
let _ = alphaTransition
return CGSize(width: availableSize.width, height: contentHeight)
```
Insert the trigger block **before** `return`:
```swift
contentHeight += 104.0
let _ = alphaTransition
if let hint = transition.userData(TextFieldComponent.AnimationHint.self), case .textChanged = hint.kind, let hintView = hint.view {
self.recenterCaret(hintView: hintView, transition: transition)
}
return CGSize(width: availableSize.width, height: contentHeight)
```
Do NOT match on `.textFocusChanged` — per the user's requirement, scrolling fires only on text edits.
- [ ] **Step 2: Ensure `TextFieldComponent` is importable**
`TextFieldComponent.AnimationHint` is vended from the `TextFieldComponent` module. Check the file's import list at the top (lines 1-25). `TextFieldComponent` is used transitively today via `ListMultilineTextFieldItemComponent`, but the type is only re-exposed if we explicitly import it.
Locate the import block (around lines 1-25). If `import TextFieldComponent` is not present, add it alphabetically — for example, between `import ResizableSheetComponent` and `import TelegramCore`:
```swift
import TextFieldComponent
```
If it is already present, skip this sub-step.
- [ ] **Step 3: Ensure the BUILD dep is present**
Locate the sibling `BUILD` file:
```bash
cat submodules/TelegramUI/Components/TextProcessingScreen/BUILD
```
Look for `//submodules/TelegramUI/Components/TextFieldComponent:TextFieldComponent` in the `deps` list. If present, skip to the next step. If absent, add it to the `deps` array (preserving alphabetical order where the BUILD file follows that convention). For example:
```
"//submodules/TelegramUI/Components/TextFieldComponent:TextFieldComponent",
```
- [ ] **Step 4: Verify compilation**
Re-run the build command from Task 1 Step 4.
Expected: clean build for `TextStyleEditScreen.swift` and its host module (`TextProcessingScreen`). Common failure modes:
- `cannot find 'TextFieldComponent' in scope` → missing `import TextFieldComponent` (fix in Step 2).
- Bazel link error naming `TextFieldComponent` → missing BUILD dep (fix in Step 3).
- `instance method requires the types 'X' and 'Y' to be equivalent` on the `case .textChanged = hint.kind` line → the `case let` pattern binding; verify with `grep -n 'case \\.textChanged' submodules/TelegramUI/Components/TextFieldComponent/Sources/TextFieldComponent.swift` that the case is payload-less (it is, per `TextFieldComponent.swift:95-103` where `Kind` declares `case textChanged` without associated values and `case textFocusChanged(isFocused: Bool)` with one).
- [ ] **Step 5: Do not commit yet** — verify end-to-end behavior in Task 4 first.
---
## Task 4: Manual smoke test and commit
**Files:**
- Modify (commit): `submodules/TelegramUI/Components/TextProcessingScreen/Sources/TextStyleEditScreen.swift`
- Possibly modify (commit): `submodules/TelegramUI/Components/TextProcessingScreen/BUILD`
- [ ] **Step 1: Launch the app on the simulator**
Run:
```bash
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 --configuration=debug_sim_arm64
```
Expected: `Telegram.ipa` target built successfully, 0 errors.
Note: this project has no unit tests; feature correctness for UI changes requires a manual check on device or simulator. Install the built app on the iOS simulator (`xcrun simctl install booted ...` if not done by the build script) and navigate to the AI style-edit sheet — this is typically reached from a chat's AI compose-mode style selector or from Settings, depending on build flavour. If the entry point is unclear, grep for `TextStyleEditScreen(` to find a test harness or the production call site:
```bash
grep -rn "TextStyleEditScreen(" submodules --include="*.swift"
```
- [ ] **Step 2: Smoke test — short content path**
1. Tap the "Style Name" field. Confirm the keyboard slides up and the "Create" button rides above the keyboard (pre-existing behavior from the earlier `inputHeight` work).
2. Type one character. With short content no scroll should occur; the scroll view should remain at origin zero (visual check: the emoji icon at the top stays visible).
Pass criterion: no visual regression; the title field is visible and typable.
- [ ] **Step 3: Smoke test — long prompt path**
1. Tap the "Instructions" field.
2. Type enough text (or paste a paragraph) to make the prompt field taller than the viewport with the keyboard up.
3. Continue typing so new characters appear at the caret.
Pass criterion: as each newline is added, the caret stays approximately 24pt above the keyboard/button area. The field's top may scroll out of view — that's expected.
- [ ] **Step 4: Smoke test — manual-scroll-then-type**
1. Still in the "Instructions" field with enough content that scroll is possible.
2. Manually drag the sheet content up so the caret is pushed above the visible area.
3. Type one character.
Pass criterion: the scroll view snaps downward so the caret is visible again, above the keyboard with the configured inset.
- [ ] **Step 5: Smoke test — edit-mode mid-field tap (non-goal regression check)**
1. Trigger the screen in edit mode on a style with a long pre-populated prompt (enough text to exceed the viewport).
2. Tap **in the middle** of the prompt so the caret lands off-screen-top (no text change).
Pass criterion: **no** scroll occurs (this is per the non-goal — we only scroll on text change). A follow-up text edit is expected to trigger a scroll; that is covered by Step 3.
- [ ] **Step 6: Check for regressions in adjacent flows**
Briefly exercise:
1. The emoji-selection sheet (tap the big round emoji area at the top) — must still open, select, and dismiss without issue.
2. The "Add a link to my account" checkbox — toggling still flips the check.
3. The "Delete Style" row (edit mode) — still pushes the confirm alert.
Pass criterion: all three work as before.
- [ ] **Step 7: Commit**
```bash
git add submodules/TelegramUI/Components/TextProcessingScreen/Sources/TextStyleEditScreen.swift
# Only stage the BUILD file if it was modified in Task 3 Step 3:
git status --short submodules/TelegramUI/Components/TextProcessingScreen/BUILD
# If the BUILD file shows up modified, stage it too:
git add submodules/TelegramUI/Components/TextProcessingScreen/BUILD
git commit -m "$(cat <<'EOF'
TextStyleEditScreen: scroll caret into view on text change
Tag both ListMultilineTextFieldItemComponents and, at the tail of
TextStyleEditContentComponent.View.update(...), read TextFieldComponent.
AnimationHint off the transition userData. On a .textChanged hint, locate
the editing field, compute the caret rect, walk up to the enclosing
ResizableSheetComponent scroll view, and adjust bounds.origin.y so the
caret sits ~24pt above the keyboard/bottom action area.
Scroll runs only on text edits (not on focus/selection changes) per spec.
Uses the direct-assign + additive-animate pattern from ComposePollScreen.
EOF
)"
```
Expected: commit succeeds. The diff is ~50 lines added across one .swift file (and possibly one line added to BUILD).
---
## Out-of-scope / follow-ups
None planned. The non-goals called out in the spec (scroll on focus change, scroll on selection change, scroll on keyboard show/hide independently of a text edit) are intentional omissions, not deferred work.
If manual smoke testing reveals that focus-gain keyboard appearance creates a bad UX (user taps a field near the bottom and the keyboard covers it until they type), consider adding back the `.textFocusChanged(isFocused: true)` case in the trigger block. That is a one-line change to the conditional in Task 3 Step 1 and does not require any design iteration.

944
docs/superpowers/plans/2026-04-24-contactlistpeer-engine-peer-migration.md
View file

@ -1,944 +0,0 @@
# Wave 36: `ContactListPeer.peer: Peer → EnginePeer` Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Migrate the public enum case `ContactListPeer.peer(peer: Peer, isGlobal: Bool, participantCount: Int32?)` from the Postbox `Peer` protocol to the TelegramCore `EnginePeer` enum in a single atomic commit. Cascading changes: change `ContactListPeer.indexName` return type from `PeerIndexNameRepresentation` to `EnginePeer.IndexName` (drops 2 `EnginePeer.IndexName(...)` wraps at one call site); rewrite the enum's custom `==` to use `EnginePeer`'s synthesized Equatable; drop 20 outflow `._asPeer()` bridges, 16 inflow `EnginePeer(peer)` wraps; rewrite 2 Postbox-concrete cast chains to EnginePeer case patterns.
**Architecture:** One atomic commit. The enum-case payload change is necessarily atomic. `ContactListPeer` lives in `submodules/AccountContext/Sources/ContactSelectionController.swift`; 7 consumer files touched in addition. 2 consumer files verified untouched (`ComposeController.swift`, `ChatSendAudioMessageContextPreview.swift`). No new wrappers, no new typealiases. `import Postbox` stays in every touched consumer (follow-up unused-import sweep handles it).
**Tech Stack:** Swift, Bazel build via Make.py wrapper. No tests — verification is build success + targeted grep checks.
**Spec:** `docs/superpowers/specs/2026-04-24-contactlistpeer-engine-peer-migration-design.md`
---
## File Structure
**Modified files (8 expected — 1 definition + 7 consumer. Plus 2 verify-only.)**
| File | Edits | Categories |
|---|---|---|
| `submodules/AccountContext/Sources/ContactSelectionController.swift` | 3 (case type + indexName return type + `==` body) | α |
| `submodules/ContactListUI/Sources/ContactListNode.swift` | ~21 (12 outflow + 4 inflow + 2 cast rewrites [L182-186, L1968] + 2 IndexName wraps [L517]) | β + δ + φ + ε′ |
| `submodules/ContactListUI/Sources/ContactsController.swift` | 1 (inflow wrap at L294) | δ |
| `submodules/ContactListUI/Sources/ContactsSearchContainerNode.swift` | 7 (3 outflow + 4 inflow) | β + δ |
| `submodules/TelegramUI/Sources/ContactMultiselectionController.swift` | 6 (2 outflow + 4 inflow) | β + δ |
| `submodules/TelegramUI/Sources/ContactMultiselectionControllerNode.swift` | 2 (1 outflow + 1 inflow) | β + δ |
| `submodules/TelegramUI/Sources/ContactSelectionController.swift` | 2 (inflow wraps L517/527) | δ |
| `submodules/TelegramUI/Sources/ContactSelectionControllerNode.swift` | 2 (outflow bridges L160/230) | β |
**Verify-only (no edits expected):**
| File | Reason |
|---|---|
| `submodules/TelegramUI/Sources/ComposeController.swift` | Destructures at L120/160 access `.id` only. Same-type access works on EnginePeer. |
| `submodules/TelegramUI/Components/Chat/ChatSendAudioMessageContextPreview/Sources/ChatSendAudioMessageContextPreview.swift` | Only holds `[ContactListPeer]` at collection level; no `.peer` destructures. |
**EnginePeer enum case mapping (used in cast rewrites):**
| Postbox concrete | EnginePeer case |
|---|---|
| `TelegramUser` | `.user(TelegramUser)` |
| `TelegramGroup` | `.legacyGroup(TelegramGroup)` |
| `TelegramChannel` | `.channel(TelegramChannel)` |
**Sites that stay as `._asPeer()` bridges (NOT in wave scope):**
- `submodules/ContactListUI/Sources/ContactsSearchContainerNode.swift:488, 528, 562` — `canSendMessagesToPeer(peer._asPeer())` / `canSendMessagesToPeer(peer.peer._asPeer())`. `canSendMessagesToPeer(_: Peer)` migration is a deferred future wave.
- `submodules/TelegramUI/Sources/ContactMultiselectionController.swift:171, 201, 748` — `peerTokenTitle(accountPeerId:..., peer: peer._asPeer(), strings:...)`. `peerTokenTitle(peer: Peer)` migration is out of scope.
---
## Task 1: Edit `AccountContext/Sources/ContactSelectionController.swift` — definition
**Files:**
- Modify: `submodules/AccountContext/Sources/ContactSelectionController.swift`
Foundational change. Without it, none of the consumer edits compile.
- [ ] **Step 1.1: Update the case payload type, `indexName` return type, and `==` operator body**
Edit using the Edit tool:
```swift
// OLD (lines 61-99)
public enum ContactListPeer: Equatable {
case peer(peer: Peer, isGlobal: Bool, participantCount: Int32?)
case deviceContact(DeviceContactStableId, DeviceContactBasicData)
public var id: ContactListPeerId {
switch self {
case let .peer(peer, _, _):
return .peer(peer.id)
case let .deviceContact(id, _):
return .deviceContact(id)
}
}
public var indexName: PeerIndexNameRepresentation {
switch self {
case let .peer(peer, _, _):
return peer.indexName
case let .deviceContact(_, contact):
return .personName(first: contact.firstName, last: contact.lastName, addressNames: [], phoneNumber: "")
}
}
public static func ==(lhs: ContactListPeer, rhs: ContactListPeer) -> Bool {
switch lhs {
case let .peer(lhsPeer, lhsIsGlobal, lhsParticipantCount):
if case let .peer(rhsPeer, rhsIsGlobal, rhsParticipantCount) = rhs, lhsPeer.isEqual(rhsPeer), lhsIsGlobal == rhsIsGlobal, lhsParticipantCount == rhsParticipantCount {
return true
} else {
return false
}
case let .deviceContact(id, contact):
if case .deviceContact(id, contact) = rhs {
return true
} else {
return false
}
}
}
}
```
```swift
// NEW
public enum ContactListPeer: Equatable {
case peer(peer: EnginePeer, isGlobal: Bool, participantCount: Int32?)
case deviceContact(DeviceContactStableId, DeviceContactBasicData)
public var id: ContactListPeerId {
switch self {
case let .peer(peer, _, _):
return .peer(peer.id)
case let .deviceContact(id, _):
return .deviceContact(id)
}
}
public var indexName: EnginePeer.IndexName {
switch self {
case let .peer(peer, _, _):
return peer.indexName
case let .deviceContact(_, contact):
return .personName(first: contact.firstName, last: contact.lastName, addressNames: [], phoneNumber: "")
}
}
public static func ==(lhs: ContactListPeer, rhs: ContactListPeer) -> Bool {
switch lhs {
case let .peer(lhsPeer, lhsIsGlobal, lhsParticipantCount):
if case let .peer(rhsPeer, rhsIsGlobal, rhsParticipantCount) = rhs, lhsPeer == rhsPeer, lhsIsGlobal == rhsIsGlobal, lhsParticipantCount == rhsParticipantCount {
return true
} else {
return false
}
case let .deviceContact(id, contact):
if case .deviceContact(id, contact) = rhs {
return true
} else {
return false
}
}
}
}
```
Three changes in this edit:
1. Line 62: `peer: Peer` → `peer: EnginePeer`
2. Line 74: return type `PeerIndexNameRepresentation` → `EnginePeer.IndexName`
3. Line 86 (inside the `==` operator): `lhsPeer.isEqual(rhsPeer)` → `lhsPeer == rhsPeer`
`EnginePeer.IndexName.personName(first:last:addressNames:phoneNumber:)` has the same labels/types as `PeerIndexNameRepresentation.personName`, so line 79 body is untouched — only its return target enum changes.
- [ ] **Step 1.2: Verify**
Run:
```bash
grep -nE "case peer\(peer:|public var indexName:|\.isEqual\(" submodules/AccountContext/Sources/ContactSelectionController.swift
```
Expected output:
- Line 62: `case peer(peer: EnginePeer, ...)`
- Line 74: `public var indexName: EnginePeer.IndexName {`
- No `isEqual(` match on the `==` path (the only remaining occurrences would be unrelated).
Do not commit yet.
---
## Task 2: Edit `ContactListNode.swift` — largest consumer, multi-category
**Files:**
- Modify: `submodules/ContactListUI/Sources/ContactListNode.swift`
Most changes happen here: 12 outflow bridges + 4 inflow wraps + 2 cast chain rewrites + 2 IndexName wrap drops.
- [ ] **Step 2.1: Drop the 12 outflow `._asPeer()` bridges via `replace_all`**
All 12 `._asPeer()` bridges at ContactListPeer.peer construction sites follow the shape `._asPeer(), isGlobal:`. Non-construction `._asPeer()` uses in this file (if any) feed other functions and do NOT use this exact substring.
Pre-flight verify:
```bash
grep -cE "\._asPeer\(\), isGlobal:" submodules/ContactListUI/Sources/ContactListNode.swift
```
Expected: `12`.
If the count is 12, apply the Edit tool with `replace_all=true`:
- `old_string`: `._asPeer(), isGlobal:`
- `new_string`: `, isGlobal:`
If the count is not 12, fall back to per-site Edits at lines 632, 690, 701, 747, 765, 1365, 1647, 1656, 1693, 1731, 1942, 1944 using enough surrounding context to make each `old_string` unique.
- [ ] **Step 2.2: Verify the 12 outflow drops**
Run:
```bash
grep -nE "\._asPeer\(\), isGlobal:" submodules/ContactListUI/Sources/ContactListNode.swift
```
Expected: zero matches.
- [ ] **Step 2.3: Drop 2 inflow wraps at L204**
Read lines 200–210 first to confirm the line text.
Edit:
```swift
// OLD (line 204)
itemPeer = .peer(peer: EnginePeer(peer), chatPeer: EnginePeer(peer))
```
```swift
// NEW
itemPeer = .peer(peer: peer, chatPeer: peer)
```
- [ ] **Step 2.4: Drop 1 inflow wrap at L252**
Read lines 248–256 first to confirm.
Edit:
```swift
// OLD (line 252)
interaction.openDisabledPeer(EnginePeer(peer), requiresPremiumForMessaging ? .premiumRequired : .generic)
```
```swift
// NEW
interaction.openDisabledPeer(peer, requiresPremiumForMessaging ? .premiumRequired : .generic)
```
- [ ] **Step 2.5: Drop 1 inflow wrap at L844**
Read lines 840–848 first to confirm.
Edit:
```swift
// OLD (line 844)
if let isPeerEnabled, !isPeerEnabled(EnginePeer(peer)) {
```
```swift
// NEW
if let isPeerEnabled, !isPeerEnabled(peer) {
```
- [ ] **Step 2.6: Rewrite the L182-186 cast chain to EnginePeer case patterns**
Read lines 176–200 first. The cast chain is inside the ContactListPeer.peer destructure at line 177.
Edit:
```swift
// OLD (lines 182-186)
} else {
if let _ = peer as? TelegramUser {
status = .presence(presence ?? EnginePeer.Presence(status: .longTimeAgo, lastActivity: 0), dateTimeFormat)
} else if let group = peer as? TelegramGroup {
status = .custom(string: NSAttributedString(string: strings.Conversation_StatusMembers(Int32(group.participantCount))), multiline: false, isActive: false, icon: nil)
} else if let channel = peer as? TelegramChannel {
```
```swift
// NEW
} else {
if case .user = peer {
status = .presence(presence ?? EnginePeer.Presence(status: .longTimeAgo, lastActivity: 0), dateTimeFormat)
} else if case let .legacyGroup(group) = peer {
status = .custom(string: NSAttributedString(string: strings.Conversation_StatusMembers(Int32(group.participantCount))), multiline: false, isActive: false, icon: nil)
} else if case let .channel(channel) = peer {
```
`channel.info` access inside the surviving inner block continues to compile unchanged (`EnginePeer.channel` wraps `TelegramChannel`). `group.participantCount` inside the `legacyGroup` branch works identically. The first branch doesn't bind the user — the `case .user = peer` form preserves that.
- [ ] **Step 2.7: Rewrite the L1968 cast to an EnginePeer case pattern**
Read lines 1964–1976 first. The cast is inside the ContactListPeer.peer destructure at line 1966.
Edit:
```swift
// OLD (lines 1967-1968)
if requirePhoneNumbers,
let user = peer as? TelegramUser {
```
```swift
// NEW
if requirePhoneNumbers,
case let .user(user) = peer {
```
`user.phone` on the following line continues to compile (`EnginePeer.user` wraps `TelegramUser`).
- [ ] **Step 2.8: Drop 2 IndexName wraps at L517**
Read lines 515–522 first.
Edit:
```swift
// OLD (line 517)
let result = EnginePeer.IndexName(lhs.indexName).isLessThan(other: EnginePeer.IndexName(rhs.indexName), ordering: sortOrder)
```
```swift
// NEW
let result = lhs.indexName.isLessThan(other: rhs.indexName, ordering: sortOrder)
```
`ContactListPeer.indexName` now returns `EnginePeer.IndexName` (from Task 1), and `isLessThan(other:ordering:)` is defined on `EnginePeer.IndexName` at `submodules/LocalizedPeerData/Sources/PeerTitle.swift:64`, so the wrap idiom is no longer required.
- [ ] **Step 2.9: Verify ContactListNode.swift changes**
Run:
```bash
grep -nE "\._asPeer\(\), isGlobal:|EnginePeer\(peer\)|peer as\? Telegram(User|Group|Channel)\b|EnginePeer\.IndexName\(lhs\.indexName\)|EnginePeer\.IndexName\(rhs\.indexName\)" submodules/ContactListUI/Sources/ContactListNode.swift
```
Expected output: only `EnginePeer(peer)` matches at lines 1819 and 1825 (out-of-scope; `peer` there is from `entryData.renderedPeer.peer`, raw `Peer`, wraps stay). Similarly, `peer as? TelegramChannel` at 1802/1820 and `peer is TelegramGroup` at 1818 stay.
If any other match appears, re-examine that site and apply the matching fix.
---
## Task 3: Edit `ContactsController.swift` — 1 inflow wrap drop
**Files:**
- Modify: `submodules/ContactListUI/Sources/ContactsController.swift`
- [ ] **Step 3.1: Drop inflow wrap at L294**
Read lines 285–300 first.
Edit:
```swift
// OLD (line 294)
strongSelf.context.sharedContext.navigateToChatController(NavigateToChatControllerParams(navigationController: navigationController, context: strongSelf.context, chatLocation: .peer(EnginePeer(peer)), purposefulAction: { [weak self] in
```
```swift
// NEW
strongSelf.context.sharedContext.navigateToChatController(NavigateToChatControllerParams(navigationController: navigationController, context: strongSelf.context, chatLocation: .peer(peer), purposefulAction: { [weak self] in
```
`peer` here is destructured from the ContactListPeer.peer case at line 287; post-migration it is already `EnginePeer`. `chatLocation: .peer(EnginePeer)` case takes `EnginePeer`.
- [ ] **Step 3.2: Verify**
Run:
```bash
grep -nE "chatLocation: \.peer\(EnginePeer\(peer\)\)" submodules/ContactListUI/Sources/ContactsController.swift
```
Expected: zero matches.
---
## Task 4: Edit `ContactsSearchContainerNode.swift` — 3 outflow + 4 inflow
**Files:**
- Modify: `submodules/ContactListUI/Sources/ContactsSearchContainerNode.swift`
- [ ] **Step 4.1: Drop the 3 outflow `._asPeer()` bridges at L494/535/569**
Use the same `._asPeer(), isGlobal:` pattern as Task 2.1. The 3 bridges at `ContactListPeer.peer(...)` constructions all match this substring; the 3 unrelated bridges at L488/528/562 (`canSendMessagesToPeer(...)` sites) do NOT match (they lack the `, isGlobal:` suffix).
Pre-flight verify:
```bash
grep -cE "\._asPeer\(\), isGlobal:" submodules/ContactListUI/Sources/ContactsSearchContainerNode.swift
```
Expected: `3`.
Apply Edit with `replace_all=true`:
- `old_string`: `._asPeer(), isGlobal:`
- `new_string`: `, isGlobal:`
- [ ] **Step 4.2: Drop 4 inflow wraps at L164/165/181**
Read lines 160–185 first.
Three edits, each targeting one source line.
Edit (line 164 — 2 wraps in one expression):
```swift
// OLD
peerItem = .peer(peer: EnginePeer(peer), chatPeer: EnginePeer(peer))
```
```swift
// NEW
peerItem = .peer(peer: peer, chatPeer: peer)
```
Edit (line 165):
```swift
// OLD
nativePeer = EnginePeer(peer)
```
```swift
// NEW
nativePeer = peer
```
Edit (line 181):
```swift
// OLD
openDisabledPeer(EnginePeer(peer), requiresPremiumForMessaging ? .premiumRequired : .generic)
```
```swift
// NEW
openDisabledPeer(peer, requiresPremiumForMessaging ? .premiumRequired : .generic)
```
- [ ] **Step 4.3: Verify**
Run:
```bash
grep -nE "\._asPeer\(\), isGlobal:|EnginePeer\(peer\)" submodules/ContactListUI/Sources/ContactsSearchContainerNode.swift
```
Expected: zero matches.
The `._asPeer()` calls at L488/528/562 (feeding `canSendMessagesToPeer`) should remain. Verify:
```bash
grep -nE "canSendMessagesToPeer\(.*\._asPeer\(\)\)" submodules/ContactListUI/Sources/ContactsSearchContainerNode.swift
```
Expected: 3 matches (L488, L528, L562).
---
## Task 5: Edit `TelegramUI/Sources/ContactMultiselectionController.swift` — 2 outflow + 4 inflow
**Files:**
- Modify: `submodules/TelegramUI/Sources/ContactMultiselectionController.swift`
- [ ] **Step 5.1: Drop 2 outflow bridges at L451/459 via `replace_all`**
Pre-flight verify:
```bash
grep -cE "\._asPeer\(\), isGlobal:" submodules/TelegramUI/Sources/ContactMultiselectionController.swift
```
Expected: `2`.
Apply Edit with `replace_all=true`:
- `old_string`: `._asPeer(), isGlobal:`
- `new_string`: `, isGlobal:`
Unrelated `._asPeer()` calls at L171/201/748 (feeding `peerTokenTitle(peer: Peer, ...)`) do NOT use this substring and stay.
- [ ] **Step 5.2: Drop 4 inflow wraps at L386/403/481/491**
Read the file around each site to confirm exact text. Two wraps (L386, L403) have identical text; the other two (L481, L491) have distinct tails.
Edit for L386 and L403 — `replace_all=true` on the substring:
Pre-flight verify:
```bash
grep -cE "subject: \.peer\(EnginePeer\(peer\)\)" submodules/TelegramUI/Sources/ContactMultiselectionController.swift
```
Expected: `2`.
Apply Edit with `replace_all=true`:
- `old_string`: `subject: .peer(EnginePeer(peer))`
- `new_string`: `subject: .peer(peer)`
Edit for L481:
```swift
// OLD
self.params.sendMessage?(EnginePeer(peer))
```
```swift
// NEW
self.params.sendMessage?(peer)
```
Edit for L491:
```swift
// OLD
self.params.openProfile?(EnginePeer(peer))
```
```swift
// NEW
self.params.openProfile?(peer)
```
- [ ] **Step 5.3: Verify**
Run:
```bash
grep -nE "\._asPeer\(\), isGlobal:|subject: \.peer\(EnginePeer\(peer\)\)|sendMessage\?\(EnginePeer\(peer\)\)|openProfile\?\(EnginePeer\(peer\)\)" submodules/TelegramUI/Sources/ContactMultiselectionController.swift
```
Expected: zero matches.
Preserved bridge sites (sanity check):
```bash
grep -nE "peerTokenTitle\(.*\._asPeer\(\)" submodules/TelegramUI/Sources/ContactMultiselectionController.swift
```
Expected: 3 matches (L171, L201, L748).
---
## Task 6: Edit `TelegramUI/Sources/ContactMultiselectionControllerNode.swift` — 1 outflow + 1 inflow
**Files:**
- Modify: `submodules/TelegramUI/Sources/ContactMultiselectionControllerNode.swift`
- [ ] **Step 6.1: Drop 1 outflow bridge at L317**
Read lines 315–320 first.
Edit:
```swift
// OLD (line 317)
self?.openPeer?(.peer(peer: peer._asPeer(), isGlobal: false, participantCount: nil))
```
```swift
// NEW
self?.openPeer?(.peer(peer: peer, isGlobal: false, participantCount: nil))
```
- [ ] **Step 6.2: Drop 1 inflow wrap at L492**
Read lines 488–495 first.
Edit:
```swift
// OLD (line 492)
callTitle = self.presentationData.strings.NewCall_ActionCallSingle(EnginePeer(peer).compactDisplayTitle).string
```
```swift
// NEW
callTitle = self.presentationData.strings.NewCall_ActionCallSingle(peer.compactDisplayTitle).string
```
- [ ] **Step 6.3: Verify**
Run:
```bash
grep -nE "\._asPeer\(\), isGlobal:|EnginePeer\(peer\)\.compactDisplayTitle" submodules/TelegramUI/Sources/ContactMultiselectionControllerNode.swift
```
Expected: zero matches.
---
## Task 7: Edit `TelegramUI/Sources/ContactSelectionController.swift` — 2 inflow wraps
**Files:**
- Modify: `submodules/TelegramUI/Sources/ContactSelectionController.swift`
- [ ] **Step 7.1: Drop 2 inflow wraps at L517/527**
Read lines 510–535 first. Both sites are inside the destructure at L504.
Edit for L517:
```swift
// OLD
self.sendMessage?(EnginePeer(peer))
```
```swift
// NEW
self.sendMessage?(peer)
```
Edit for L527:
```swift
// OLD
self.openProfile?(EnginePeer(peer))
```
```swift
// NEW
self.openProfile?(peer)
```
- [ ] **Step 7.2: Verify**
Run:
```bash
grep -nE "sendMessage\?\(EnginePeer\(peer\)\)|openProfile\?\(EnginePeer\(peer\)\)" submodules/TelegramUI/Sources/ContactSelectionController.swift
```
Expected: zero matches.
---
## Task 8: Edit `TelegramUI/Sources/ContactSelectionControllerNode.swift` — 2 outflow bridges
**Files:**
- Modify: `submodules/TelegramUI/Sources/ContactSelectionControllerNode.swift`
- [ ] **Step 8.1: Drop 2 outflow bridges at L160/230 via `replace_all`**
Pre-flight verify:
```bash
grep -cE "\._asPeer\(\), isGlobal:" submodules/TelegramUI/Sources/ContactSelectionControllerNode.swift
```
Expected: `2`.
Apply Edit with `replace_all=true`:
- `old_string`: `._asPeer(), isGlobal:`
- `new_string`: `, isGlobal:`
- [ ] **Step 8.2: Verify**
Run:
```bash
grep -nE "\._asPeer\(\), isGlobal:" submodules/TelegramUI/Sources/ContactSelectionControllerNode.swift
```
Expected: zero matches.
---
## Task 9: Verify no-edit consumer files
**Files (read only):**
- Read: `submodules/TelegramUI/Sources/ComposeController.swift`
- Read: `submodules/TelegramUI/Components/Chat/ChatSendAudioMessageContextPreview/Sources/ChatSendAudioMessageContextPreview.swift`
- [ ] **Step 9.1: Confirm ComposeController.swift has no inflow wraps, casts, or outflow bridges**
Run:
```bash
grep -nE "\.peer\(peer:|EnginePeer\(peer\)|peer as\? Telegram|\._asPeer\(\)" submodules/TelegramUI/Sources/ComposeController.swift
```
Expected: zero matches (destructures at L120/160 only access `.id`).
If any match appears, add the appropriate fix step here and re-run Task 9.1 before proceeding.
- [ ] **Step 9.2: Confirm ChatSendAudioMessageContextPreview.swift has no ContactListPeer.peer destructures**
Run:
```bash
grep -nE "case let \.peer\(peer, _, _\)|case \.peer\(let peer|EnginePeer\(peer\)|\.peer\(peer: " submodules/TelegramUI/Components/Chat/ChatSendAudioMessageContextPreview/Sources/ChatSendAudioMessageContextPreview.swift
```
Expected: zero matches. The file only references `[ContactListPeer]` at the collection level.
---
## Task 10: Build verification (first pass)
- [ ] **Step 10.1: Run the full build with `--continueOnError`**
Run:
```bash
source ~/.zshrc 2>/dev/null && python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 --configuration=debug_sim_arm64 --continueOnError 2>&1 | tee /tmp/wave36-build.log
```
Expected outcome: ideally clean. Realistic: 0–3 inventory-missed sites (wave 35 trend was 14% miss rate on a 7-file wave; this 8-file wave has a larger surface area, so budget for up to 3 misses).
- [ ] **Step 10.2: Triage build errors**
Likely patterns and fixes:
| Error | Fix |
|---|---|
| `cannot convert value of type 'EnginePeer' to expected argument type 'Peer'` at a call site | Add `._asPeer()` bridge. The callee takes raw `Peer` and is out of wave scope. |
| `cannot convert value of type 'Peer' to expected argument type 'EnginePeer'` at a `.peer(peer:, ...)` construction | Wrap raw peer with `EnginePeer(...)`. The raw-Peer source is probably from `transaction.getPeer(...)` or similar. |
| `value of type 'EnginePeer' has no member 'isEqual'` | Replace with `==`. |
| `type 'EnginePeer' cannot be cast to 'TelegramUser'` / `TelegramGroup` / `TelegramChannel` | Missed φ-category cast — rewrite to `case .user = peer` / `case let .legacyGroup(x) = peer` / `case let .channel(x) = peer`. |
| `cannot invoke initializer for type 'EnginePeer' with an argument list of type '(EnginePeer)'` | Missed inflow drop — strip `EnginePeer(...)` wrap. |
| `cannot convert value of type 'EnginePeer.IndexName' to expected argument type 'PeerIndexNameRepresentation'` | Either wrap the call site's expected-type change or adjust the consumer to accept `EnginePeer.IndexName`. Probably rare — ContactListPeer.indexName consumers were grepped in pre-flight and found only in ContactListNode. |
| `value of type 'EnginePeer' has no member '<postbox-Peer-only method>'` | That method is only on the Postbox `Peer` protocol. Bridge via `._asPeer()` OR find the EnginePeer-native equivalent. |
For each error: identify file:line, apply the fix, re-run the build until clean.
- [ ] **Step 10.3: Iterate to clean build**
Re-run the build after each batch of fixes. The wave is complete when the build returns 0 errors for the targeted configuration.
If 10+ unexpected errors surface, halt and reassess: the inventory may have significantly undercounted and the wave may need to be split. Discuss with the user before continuing.
---
## Task 11: Post-build grep validations
- [ ] **Step 11.1: Outflow-bridge-drop validation**
Run:
```bash
grep -rnE "\.peer\(peer: \w+\._asPeer\(\), isGlobal:" submodules/ --include="*.swift"
```
Expected: zero hits. Any remaining site is a missed outflow-bridge drop.
- [ ] **Step 11.2: Inflow-wrap-drop validation**
Run:
```bash
for f in submodules/ContactListUI/Sources/ContactListNode.swift \
submodules/ContactListUI/Sources/ContactsController.swift \
submodules/ContactListUI/Sources/ContactsSearchContainerNode.swift \
submodules/TelegramUI/Sources/ContactMultiselectionController.swift \
submodules/TelegramUI/Sources/ContactMultiselectionControllerNode.swift \
submodules/TelegramUI/Sources/ContactSelectionController.swift; do
echo "=== $f ==="
grep -nE "EnginePeer\(peer\)" "$f"
done
```
Expected hits:
- ContactListNode.swift L1819, L1825 (raw `renderedPeer.peer`, out-of-scope wraps stay)
- Any other hit in the 6 listed files is a missed inflow drop — inspect and fix.
- [ ] **Step 11.3: Cast-rewrite validation**
Run:
```bash
grep -nE "\bpeer (as\?|as!|is) Telegram(User|Group|Channel)\b" submodules/ContactListUI/Sources/ContactListNode.swift
```
Expected: only L1802, L1818, L1820 remain (out-of-scope, `peer` is raw from `renderedPeer.peer`).
If L182, L184, L186, or L1968 appear, those are missed φ rewrites.
- [ ] **Step 11.4: IndexName wrap validation**
Run:
```bash
grep -nE "EnginePeer\.IndexName\(lhs\.indexName\)|EnginePeer\.IndexName\(rhs\.indexName\)" submodules/ContactListUI/Sources/ContactListNode.swift
```
Expected: zero matches.
- [ ] **Step 11.5: isEqual-in-==-operator validation**
Run:
```bash
grep -nE "lhsPeer\.isEqual\(rhsPeer\)" submodules/AccountContext/Sources/ContactSelectionController.swift
```
Expected: zero matches.
- [ ] **Step 11.6: Construction-site sanity sweep**
Run:
```bash
grep -rnE "ContactListPeer\.peer\(peer: |\.peer\(peer: \w+, isGlobal:" submodules/ --include="*.swift" | head -40
```
Inspect each hit. Expected forms:
- `.peer(peer: <EnginePeer-expr>, isGlobal: …)` where `<EnginePeer-expr>` is either a local already typed `EnginePeer` or `EnginePeer(<raw-Peer>)`.
- Anything of the form `.peer(peer: <raw-Peer>, isGlobal: …)` where `<raw-Peer>` is a Postbox `Peer` value is a miss (would surface as a build error — this is a belt-and-suspenders check).
If any validation fails, return to Task 10.
---
## Task 12: Atomic commit + memory + log update
- [ ] **Step 12.1: Stage and review**
Run:
```bash
git status --short
git diff --stat
```
Confirm exactly 8 modified Swift files:
- `submodules/AccountContext/Sources/ContactSelectionController.swift`
- `submodules/ContactListUI/Sources/ContactListNode.swift`
- `submodules/ContactListUI/Sources/ContactsController.swift`
- `submodules/ContactListUI/Sources/ContactsSearchContainerNode.swift`
- `submodules/TelegramUI/Sources/ContactMultiselectionController.swift`
- `submodules/TelegramUI/Sources/ContactMultiselectionControllerNode.swift`
- `submodules/TelegramUI/Sources/ContactSelectionController.swift`
- `submodules/TelegramUI/Sources/ContactSelectionControllerNode.swift`
Pre-existing WIP (`build-system/bazel-rules/sourcekit-bazel-bsp`, `ChatListFilterPresetController.swift`, `ChatListFilterPresetListController.swift`, untracked `build-system/tulsi/` / `submodules/TgVoip/` / `third-party/libx264/` / `docs/superpowers/plans/2026-04-22-claude-md-reorganization.md`) should NOT be staged.
- [ ] **Step 12.2: Stage only the wave-36 files**
Run:
```bash
git add submodules/AccountContext/Sources/ContactSelectionController.swift \
submodules/ContactListUI/Sources/ContactListNode.swift \
submodules/ContactListUI/Sources/ContactsController.swift \
submodules/ContactListUI/Sources/ContactsSearchContainerNode.swift \
submodules/TelegramUI/Sources/ContactMultiselectionController.swift \
submodules/TelegramUI/Sources/ContactMultiselectionControllerNode.swift \
submodules/TelegramUI/Sources/ContactSelectionController.swift \
submodules/TelegramUI/Sources/ContactSelectionControllerNode.swift
```
If Task 10 introduced additional files (inventory-miss fixes), append them.
- [ ] **Step 12.3: Commit**
Run:
```bash
git commit -m "$(cat <<'EOF'
Postbox -> TelegramEngine wave 36: ContactListPeer.peer Peer -> EnginePeer
Migrates the public enum case `ContactListPeer.peer(peer: Peer, isGlobal:,
participantCount:)` from the Postbox `Peer` protocol to the TelegramCore
`EnginePeer` enum. Also cascades `ContactListPeer.indexName` return type
from `PeerIndexNameRepresentation` to `EnginePeer.IndexName` and rewrites
the enum's custom `==` operator to use EnginePeer's synthesized Equatable.
Consumer-side cascade in 7 files:
- 20 `._asPeer()` outflow bridge-drops at ContactListPeer.peer
construction sites (the payload is now EnginePeer)
- 16 `EnginePeer(peer)` inflow wrap-drops at destructure sites (the
destructured `peer` is already EnginePeer)
- 2 `EnginePeer.IndexName(...)` wrap-drops at a sort-comparator (the
indexName property now returns EnginePeer.IndexName directly)
- 2 Postbox-concrete cast chains rewritten to EnginePeer case patterns
(`peer as? TelegramUser` → `case .user = peer`, etc.)
- `lhsPeer.isEqual(rhsPeer)` → `lhsPeer == rhsPeer` in the ==operator
Files modified:
submodules/AccountContext/Sources/ContactSelectionController.swift
submodules/ContactListUI/Sources/ContactListNode.swift
submodules/ContactListUI/Sources/ContactsController.swift
submodules/ContactListUI/Sources/ContactsSearchContainerNode.swift
submodules/TelegramUI/Sources/ContactMultiselectionController.swift
submodules/TelegramUI/Sources/ContactMultiselectionControllerNode.swift
submodules/TelegramUI/Sources/ContactSelectionController.swift
submodules/TelegramUI/Sources/ContactSelectionControllerNode.swift
Bridges intentionally retained (out-of-wave scope):
- `canSendMessagesToPeer(peer._asPeer())` — callee takes Peer, deferred
- `peerTokenTitle(peer: peer._asPeer(), ...)` — callee takes Peer,
deferred
Plan: docs/superpowers/plans/2026-04-24-contactlistpeer-engine-peer-migration.md
Spec: docs/superpowers/specs/2026-04-24-contactlistpeer-engine-peer-migration-design.md
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 12.4: Update CLAUDE.md wave counter**
Edit `CLAUDE.md` to bump the "Waves landed so far" line from "35 waves" to "36 waves" and update the "as of" date if the commit lands after 2026-04-24.
- [ ] **Step 12.5: Append wave outcome to the postbox-refactor-log**
Append a "Wave 36 outcome" section to `docs/superpowers/postbox-refactor-log.md` documenting:
- Actual files touched + edit counts vs. plan
- Any inventory undercounts surfaced by Task 10 (file:line + missed-category)
- Any lessons learned (e.g., whether the γ category really had zero sites; how the φ cast-rewrites behaved; post-migration undercount percentage vs wave 35's 14%)
- Ratio of bridge-drops to bridge-additions (wave theme: removal-dominated)
Keep concise.
- [ ] **Step 12.6: Commit the docs update**
Run:
```bash
git add CLAUDE.md docs/superpowers/postbox-refactor-log.md
git commit -m "$(cat <<'EOF'
docs: add wave 36 outcome (ContactListPeer.peer Peer→EnginePeer)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 12.7: Update the next-wave memory**
Edit `/Users/isaac/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/project_postbox_refactor_next_wave.md`:
- Add wave 36 to the "Latest commits" section.
- Move ContactListPeer migration from "Recommended wave 36 candidates" to landed.
- Record the inventory undercount ratio (actual-files-touched ÷ pre-flight-file-count) for calibration.
- Update the "Recommended wave 37" section. Promote candidates: `canSendMessagesToPeer(_:)` parameter (the ContactsSearchContainerNode `._asPeer()` bridges at L488/528/562 plus others elsewhere drop when this lands); `peerTokenTitle(peer:)` parameter (drops 3 bridges in ContactMultiselectionController); `makePeerInfoController` / `makeChatQrCodeScreen` / `makeChatRecentActionsController` AccountContext protocol methods (largest remaining Peer-typed-API); accountManager engine path; Shape-C `resourceData` module.
Use the Edit tool on the memory file. No git commit needed.
---
## Risks and notes
- **Inventory undercount.** Pre-flight caught several sites the Explore agent missed (inflow wraps at L481/491/517/527/492/844, cast rewrites at L182-186 and L1968). Budget for 1–3 additional misses surfacing in Task 10. If the build surfaces 5+ misses in new categories, stop and reassess.
- **`replace_all` usage.** Every `replace_all=true` Edit in this plan is gated by a pre-flight `grep -c` count check. If the count is wrong, fall back to per-site Edits with surrounding context.
- **Cast rewrite at L182-186.** The original cast chain binds `group` and `channel` (but not `user`). The EnginePeer case-pattern form preserves this: `case .user = peer` is a binding-free match, mirroring `if let _ = peer as? TelegramUser`.
- **`._asPeer()` sites that stay.** Tasks 4.3 and 5.3 explicitly verify that the 3 `canSendMessagesToPeer(peer._asPeer())` bridges and 3 `peerTokenTitle(peer: peer._asPeer(), ...)` bridges remain intact. Dropping these would be out-of-scope migration.
- **WIP isolation.** Pre-existing `ChatListFilterPresetController.swift` / `ChatListFilterPresetListController.swift` edits and untracked `build-system/tulsi/`, `submodules/TgVoip/`, `third-party/libx264/` paths are user WIP — do NOT stage them. Use the explicit `git add <files>` form in Step 12.2.
- **Scope boundary.** Task 10 errors surfacing in `TelegramCore`, `Postbox`, or `TelegramApi` mean the migration cascaded beyond its intended consumer scope. Halt and investigate — do NOT edit TelegramCore in this wave.
- **No new typealiases/wrappers.** Rule 2 and 3 of the Postbox refactor guidance apply — this wave stays inside.

1287
docs/superpowers/plans/2026-04-24-foundpeer-engine-peer-migration.md
View file

File diff suppressed because it is too large Load diff

411
docs/superpowers/plans/2026-04-24-makeChatQrCodeScreen-recentActions-engine-peer-migration.md
View file

@ -1,411 +0,0 @@
# Wave 40 — `makeChatQrCodeScreen` + `makeChatRecentActionsController` Peer → EnginePeer Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Bundle migrate two sibling `AccountContext` methods deferred from wave 39 — `makeChatQrCodeScreen` (4 consumer sites) and `makeChatRecentActionsController` (3 consumer sites) — from raw `peer: Peer` to `peer: EnginePeer`, applying the body-shadow pattern.
**Architecture:** Body-shadow pattern (wave-38/39 style). Protocol + impl signatures change to `peer: EnginePeer`; each impl body gets a `let peer = peer._asPeer()` shadow so the downstream constructors (`ChatQrCodeScreenImpl`, `ChatRecentActionsController`) remain raw-`Peer` consumers (out of scope).
**Tech Stack:** Swift, Bazel, iOS; TelegramCore / AccountContext / TelegramUI / PeerInfoUI / StatisticsUI / SettingsUI / ContactListUI / PeerInfoScreen submodules.
**Reference:** Wave-39 "Out of scope" section in `docs/superpowers/specs/2026-04-24-makePeerInfoController-engine-peer-migration-design.md`.
---
## Pre-flight classification
**`makeChatQrCodeScreen` (4 consumer sites):**
| # | Site | Shape | Edit |
|---|---|---|---|
| 1 | `SettingsSearchableItems.swift:974` | **Shape-A-variant** | Rewrite upstream `guard let peer = peer?._asPeer() else { return }` (line 971) → `guard let peer = peer else { return }`. Call stays `peer: peer`. |
| 2 | `SettingsSearchableItems.swift:992` | **Shape-A-variant** | Same pattern as #1 (upstream guard at line 989). |
| 3 | `ContactsController.swift:478` | **Shape-A** | Drop `._asPeer()` from `peer: peer._asPeer()` → `peer: peer`. Source: `Signal<EnginePeer, NoError>`. |
| 4 | `PeerInfoScreen.swift:4623` | **Shape-C** | Wrap: `peer: peer` → `peer: EnginePeer(peer)`. Source: `data.peer: Peer?`. |
**`makeChatRecentActionsController` (3 consumer sites):**
| # | Site | Shape | Edit |
|---|---|---|---|
| 5 | `ChannelAdminsController.swift:734` | **Shape-A** | Drop `._asPeer()`. Source: `engine.data.get(Peer.Peer(id:))` — `peer` is `EnginePeer` in the `guard let peer` on line 729. |
| 6 | `GroupStatsController.swift:915` | **Shape-A** | Drop `._asPeer()`. Source: `Signal<EnginePeer, NoError>` (mapToSignal at 906). |
| 7 | `PeerInfoScreenOpenChat.swift:115` | **Shape-C** | Wrap: `peer: peer` → `peer: EnginePeer(peer)`. Source: `self.data?.peer: Peer?`. |
**Net bridge delta:** −5 `_asPeer()` drops (sites 1, 2, 3, 5, 6) + 2 `EnginePeer(...)` wraps (sites 4, 7) = **−3 net**. Sites 4 and 7 become ratchet markers for a future `PeerInfoScreenData.peer Peer → EnginePeer` wave.
---
## File touch summary
8 files:
1. `submodules/AccountContext/Sources/AccountContext.swift` — protocol decls (2 lines).
2. `submodules/TelegramUI/Sources/SharedAccountContext.swift` — impl signatures + body shadows (2 sites).
3. `submodules/SettingsUI/Sources/Search/SettingsSearchableItems.swift` — 2 Shape-A-variant upstream guard rewrites.
4. `submodules/ContactListUI/Sources/ContactsController.swift` — 1 Shape-A drop.
5. `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreen.swift` — 1 Shape-C wrap.
6. `submodules/PeerInfoUI/Sources/ChannelAdminsController.swift` — 1 Shape-A drop.
7. `submodules/StatisticsUI/Sources/GroupStatsController.swift` — 1 Shape-A drop.
8. `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreenOpenChat.swift` — 1 Shape-C wrap.
---
### Task 1: Update `AccountContext` protocol signatures
**Files:**
- Modify: `submodules/AccountContext/Sources/AccountContext.swift:1401` and `:1461`
- [ ] **Step 1: Update `makeChatRecentActionsController` decl**
```swift
// old_string
func makeChatRecentActionsController(context: AccountContext, peer: Peer, adminPeerId: PeerId?, starsState: StarsRevenueStats?) -> ViewController
// new_string
func makeChatRecentActionsController(context: AccountContext, peer: EnginePeer, adminPeerId: PeerId?, starsState: StarsRevenueStats?) -> ViewController
```
- [ ] **Step 2: Update `makeChatQrCodeScreen` decl**
```swift
// old_string
func makeChatQrCodeScreen(context: AccountContext, peer: Peer, threadId: Int64?, temporary: Bool) -> ViewController
// new_string
func makeChatQrCodeScreen(context: AccountContext, peer: EnginePeer, threadId: Int64?, temporary: Bool) -> ViewController
```
---
### Task 2: Update `SharedAccountContext` impls with body-shadow
**Files:**
- Modify: `submodules/TelegramUI/Sources/SharedAccountContext.swift:2302` (makeChatRecentActionsController)
- Modify: `submodules/TelegramUI/Sources/SharedAccountContext.swift:2730` (makeChatQrCodeScreen)
- [ ] **Step 1: Update `makeChatRecentActionsController` impl**
```swift
// old_string
public func makeChatRecentActionsController(context: AccountContext, peer: Peer, adminPeerId: PeerId?, starsState: StarsRevenueStats?) -> ViewController {
return ChatRecentActionsController(context: context, peer: peer, adminPeerId: adminPeerId, starsState: starsState)
}
// new_string
public func makeChatRecentActionsController(context: AccountContext, peer: EnginePeer, adminPeerId: PeerId?, starsState: StarsRevenueStats?) -> ViewController {
let peer = peer._asPeer()
return ChatRecentActionsController(context: context, peer: peer, adminPeerId: adminPeerId, starsState: starsState)
}
```
- [ ] **Step 2: Update `makeChatQrCodeScreen` impl**
```swift
// old_string
public func makeChatQrCodeScreen(context: AccountContext, peer: Peer, threadId: Int64?, temporary: Bool) -> ViewController {
return ChatQrCodeScreenImpl(context: context, subject: .peer(peer: peer, threadId: threadId, temporary: temporary))
}
// new_string
public func makeChatQrCodeScreen(context: AccountContext, peer: EnginePeer, threadId: Int64?, temporary: Bool) -> ViewController {
let peer = peer._asPeer()
return ChatQrCodeScreenImpl(context: context, subject: .peer(peer: peer, threadId: threadId, temporary: temporary))
}
```
---
### Task 3: `SettingsSearchableItems.swift` — two Shape-A-variant guard rewrites
**Files:**
- Modify: `submodules/SettingsUI/Sources/Search/SettingsSearchableItems.swift:971` and `:989`
Both sites share the same structure: an upstream `guard let peer = peer?._asPeer() else { return }` unwraps `EnginePeer?` to `Peer`. Rewrite the guard to keep the local as `EnginePeer`; the call site below stays unchanged.
- [ ] **Step 1: Rewrite guard at line 971 (qr-code item)**
```swift
// old_string
present: { context, _, present in
let _ = (context.engine.data.get(TelegramEngine.EngineData.Item.Peer.Peer(id: context.account.peerId))
|> deliverOnMainQueue).start(next: { peer in
guard let peer = peer?._asPeer() else {
return
}
let controller = context.sharedContext.makeChatQrCodeScreen(context: context, peer: peer, threadId: nil, temporary: false)
present(.push, controller)
})
}
)
)
//TODO:fix
items.append(
SettingsSearchableItem(
id: "qr-code/share",
// new_string
present: { context, _, present in
let _ = (context.engine.data.get(TelegramEngine.EngineData.Item.Peer.Peer(id: context.account.peerId))
|> deliverOnMainQueue).start(next: { peer in
guard let peer = peer else {
return
}
let controller = context.sharedContext.makeChatQrCodeScreen(context: context, peer: peer, threadId: nil, temporary: false)
present(.push, controller)
})
}
)
)
//TODO:fix
items.append(
SettingsSearchableItem(
id: "qr-code/share",
```
- [ ] **Step 2: Rewrite guard at line 989 (qr-code/share item)**
```swift
// old_string
id: "qr-code/share",
isVisible: false,
present: { context, _, present in
let _ = (context.engine.data.get(TelegramEngine.EngineData.Item.Peer.Peer(id: context.account.peerId))
|> deliverOnMainQueue).start(next: { peer in
guard let peer = peer?._asPeer() else {
return
}
let controller = context.sharedContext.makeChatQrCodeScreen(context: context, peer: peer, threadId: nil, temporary: false)
present(.push, controller)
})
}
// new_string
id: "qr-code/share",
isVisible: false,
present: { context, _, present in
let _ = (context.engine.data.get(TelegramEngine.EngineData.Item.Peer.Peer(id: context.account.peerId))
|> deliverOnMainQueue).start(next: { peer in
guard let peer = peer else {
return
}
let controller = context.sharedContext.makeChatQrCodeScreen(context: context, peer: peer, threadId: nil, temporary: false)
present(.push, controller)
})
}
```
---
### Task 4: `ContactsController.swift` — Shape-A drop
**Files:**
- Modify: `submodules/ContactListUI/Sources/ContactsController.swift:478`
- [ ] **Step 1: Drop `._asPeer()` at the call site**
```swift
// old_string
controller.present(strongSelf.context.sharedContext.makeChatQrCodeScreen(context: strongSelf.context, peer: peer._asPeer(), threadId: nil, temporary: false), in: .window(.root))
// new_string
controller.present(strongSelf.context.sharedContext.makeChatQrCodeScreen(context: strongSelf.context, peer: peer, threadId: nil, temporary: false), in: .window(.root))
```
---
### Task 5: `PeerInfoScreen.swift` — Shape-C wrap
**Files:**
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreen.swift:4623`
Local `peer` comes from `data.peer` (type `Peer`). Wrap at the call site.
- [ ] **Step 1: Wrap with `EnginePeer(...)`**
```swift
// old_string
let qrController = self.context.sharedContext.makeChatQrCodeScreen(context: self.context, peer: peer, threadId: threadId, temporary: temporary)
// new_string
let qrController = self.context.sharedContext.makeChatQrCodeScreen(context: self.context, peer: EnginePeer(peer), threadId: threadId, temporary: temporary)
```
---
### Task 6: `ChannelAdminsController.swift` — Shape-A drop
**Files:**
- Modify: `submodules/PeerInfoUI/Sources/ChannelAdminsController.swift:734`
Local `peer` is `EnginePeer` (from `guard let peer` on :729 unwrapping `EnginePeer?` from `engine.data.get(Peer.Peer(id:))`).
- [ ] **Step 1: Drop `._asPeer()`**
```swift
// old_string
pushControllerImpl?(context.sharedContext.makeChatRecentActionsController(context: context, peer: peer._asPeer(), adminPeerId: nil, starsState: nil))
// new_string
pushControllerImpl?(context.sharedContext.makeChatRecentActionsController(context: context, peer: peer, adminPeerId: nil, starsState: nil))
```
---
### Task 7: `GroupStatsController.swift` — Shape-A drop
**Files:**
- Modify: `submodules/StatisticsUI/Sources/GroupStatsController.swift:915`
Local `peer` is `EnginePeer` (from `Signal<EnginePeer, NoError>` via the `mapToSignal` at :906).
- [ ] **Step 1: Drop `._asPeer()`**
```swift
// old_string
let controller = context.sharedContext.makeChatRecentActionsController(context: context, peer: peer._asPeer(), adminPeerId: participantPeerId, starsState: nil)
// new_string
let controller = context.sharedContext.makeChatRecentActionsController(context: context, peer: peer, adminPeerId: participantPeerId, starsState: nil)
```
---
### Task 8: `PeerInfoScreenOpenChat.swift` — Shape-C wrap
**Files:**
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreenOpenChat.swift:115`
Local `peer` comes from `self.data?.peer` (type `Peer`). Wrap at the call site.
- [ ] **Step 1: Wrap with `EnginePeer(...)`**
```swift
// old_string
let controller = self.context.sharedContext.makeChatRecentActionsController(context: self.context, peer: peer, adminPeerId: nil, starsState: self.data?.starsRevenueStatsState)
// new_string
let controller = self.context.sharedContext.makeChatRecentActionsController(context: self.context, peer: EnginePeer(peer), adminPeerId: nil, starsState: self.data?.starsRevenueStatsState)
```
---
### Task 9: Build + iterate
- [ ] **Step 1: Run full build**
```bash
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 --configuration=debug_sim_arm64 \
--continueOnError
```
Expected: first-pass-clean (wave 39's 50-file wave landed first-pass-clean; this 8-file wave should too).
- [ ] **Step 2: If errors, iterate**
Each error should point at a call site the plan missed. Fix, re-run. Do not widen the scope — if a call site not in the classification table above appears as an error, investigate whether the memory/inventory was stale.
---
### Task 10: Verify no residue
- [ ] **Step 1: Grep for raw-`Peer` sites**
```bash
grep -rn "makeChatQrCodeScreen\|makeChatRecentActionsController" --include="*.swift" submodules/
```
Expected output: 2 protocol-decl lines (AccountContext.swift), 2 impl-decl lines (SharedAccountContext.swift), and exactly 7 consumer sites — all with `peer: peer`, `peer: EnginePeer(peer)`, or similar (no `peer: x._asPeer()` remaining for these two methods).
---
### Task 11: Commit + update refactor log
**Files:**
- Modify: `docs/superpowers/postbox-refactor-log.md` — append wave-40 outcome section.
- [ ] **Step 1: Stage exactly these 8 files (enumerate, do not use `git add -u`)**
```bash
git add \
submodules/AccountContext/Sources/AccountContext.swift \
submodules/TelegramUI/Sources/SharedAccountContext.swift \
submodules/SettingsUI/Sources/Search/SettingsSearchableItems.swift \
submodules/ContactListUI/Sources/ContactsController.swift \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreen.swift \
submodules/PeerInfoUI/Sources/ChannelAdminsController.swift \
submodules/StatisticsUI/Sources/GroupStatsController.swift \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreenOpenChat.swift \
docs/superpowers/plans/2026-04-24-makeChatQrCodeScreen-recentActions-engine-peer-migration.md
```
- [ ] **Step 2: Verify staging with `git status --short`**
Verify only the 9 files above are staged. If other files appear (e.g. `ChatMessageTransitionNode.swift` WIP, `sourcekit-bazel-bsp` submodule marker) — reset them out of the index with `git restore --staged <file>` and re-check.
- [ ] **Step 3: Commit (wave 40)**
```bash
git commit -m "$(cat <<'EOF'
Postbox -> TelegramEngine wave 40
makeChatQrCodeScreen + makeChatRecentActionsController peer Peer->EnginePeer.
- AccountContext protocol: 2 decls updated
- SharedAccountContext impls: 2 signatures + 2 body-shadow `let peer = peer._asPeer()`
- 5 Shape-A `._asPeer()` drops (SettingsSearchableItems x2 guard-variant, ContactsController, ChannelAdminsController, GroupStatsController)
- 2 Shape-C `EnginePeer(peer)` wraps (PeerInfoScreen, PeerInfoScreenOpenChat)
- Net: -3 bridges
Sibling follow-up to wave 39 (makePeerInfoController). Pre-flight classification
completed in wave-39 design doc's "Out of scope" section.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 4: Log wave 40 outcome**
Append a new section to `docs/superpowers/postbox-refactor-log.md`:
```markdown
## Wave 40 outcome
Commit: `<hash>`. Bundle of `AccountContext.makeChatQrCodeScreen` + `makeChatRecentActionsController` peer `Peer → EnginePeer`. 8 files / ~12 lines changed. Pre-flight classification from wave-39 design doc held: 5 Shape-A drops + 2 Shape-C wraps + 2 impl body-shadows + 2 protocol decls. Net −3 bridges. Build outcome: <first-pass-clean | N iterations>.
Sibling follow-up to wave 39 — completes the "Option 1 cluster" (makePeerInfoController family from wave-38 memory). Ratchet markers installed at PeerInfoScreen:4623 and PeerInfoScreenOpenChat:115 for a future `PeerInfoScreenData.peer Peer → EnginePeer` wave.
```
Then commit the log update:
```bash
git add docs/superpowers/postbox-refactor-log.md
git commit -m "$(cat <<'EOF'
docs: log wave 40 outcome
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 5: Update memory**
Update `/Users/isaac/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/project_postbox_refactor_next_wave.md`:
- Move wave-40 (this bundle) from "candidates" to "Latest commits".
- Bump wave-41 recommendation to RenderedChannelParticipant.peer (Option 3) or RenderedPeer (Option 2).
- Add wave-40 lesson if any (e.g. "bundled sibling migration with shared pre-flight is cheap" or similar).
---
## Self-review checklist (writing-plans skill)
- **Spec coverage:** Every site from the memory/wave-39-doc pre-flight is a task. Sites 1+2 → Task 3; Site 3 → Task 4; Site 4 → Task 5; Site 5 → Task 6; Site 6 → Task 7; Site 7 → Task 8. Impl bodies → Task 2. Protocol → Task 1. Build → Task 9. Verify → Task 10. Commit+log → Task 11. ✓
- **Placeholders:** None. Every Edit step has exact `old_string` / `new_string`. Commit message and log-update text are spelled out. ✓
- **Type consistency:** Both methods take `peer: EnginePeer` everywhere — protocol decl, impl decl, and call sites' parameter passes. ✓

1037
docs/superpowers/plans/2026-04-24-makePeerInfoController-engine-peer-migration.md
View file

File diff suppressed because it is too large Load diff

658
docs/superpowers/plans/2026-04-24-peerinfoscreen-helpers-engine-peer-migration.md
View file

@ -1,658 +0,0 @@
# Wave 43 plan: PeerInfoScreen helpers `peer: Peer?` → `peer: EnginePeer?`
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Migrate six PeerInfoScreen module helpers (`canEditPeerInfo`, `availableActionsForMemberOfPeer`, `peerInfoHeaderActionButtons`, `peerInfoHeaderButtons`, `peerInfoCanEdit`, `peerInfoIsChatMuted`) from `peer: Peer?` to `peer: EnginePeer?`, rewriting internal `as?`/`is` against concrete `TelegramX` subclasses to `case let .x` / `case .x` enum patterns on `EnginePeer`, and updating all 21 call sites to drop wave-42-installed `._asPeer()` / `?._asPeer()` bridges or add `.flatMap(EnginePeer.init)` / `EnginePeer(...)` wraps as appropriate.
**Architecture:** In-place signature migration following wave-42 precedent — no new typealiases, no engine wrapper structs, no TelegramCore changes. All edits within `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/` (10 files). Single atomic commit.
**Tech Stack:** Swift, Bazel build, `EnginePeer` enum cases (`.user(TelegramUser)`, `.legacyGroup(TelegramGroup)`, `.channel(TelegramChannel)`, `.secretChat(TelegramSecretChat)`).
**Preceding waves:** 42 (`PeerInfoScreenData.peer: Peer? → EnginePeer?`) on 2026-04-24. This wave drops ~7 `?._asPeer()` / `._asPeer()` bridges installed then.
**Expected net wrap change:** ~7 DROPs vs ~12 ADDs → net roughly 0. The headline win is helper-signature migration, not wrap count. Follow-up waves migrating `PeerInfoHeaderEditingContentNode.update`, `PeerInfoEditingAvatarNode.update`, `PeerInfoEditingAvatarOverlayNode.update`, `PeerInfoHeaderNode.update`, `PeerInfoScreenMemberItem.enclosingPeer`, `PeerInfoMembersPane` enclosingPeer param will drop the ADDs introduced here.
**Build expectation:** 2 iterations likely (per wave-41 lesson — foundational-type migrations rarely first-pass-clean). Hedge for iteration-3 if unexpected property accesses surface.
---
## Pre-flight facts (verified from repo 2026-04-24)
### EnginePeer cases (from `submodules/TelegramCore/Sources/TelegramEngine/Peers/Peer.swift:177`)
```
case user(TelegramUser)
case legacyGroup(TelegramGroup)
case channel(TelegramChannel)
case secretChat(TelegramSecretChat)
```
Forwarded property subset on `EnginePeer` includes `id`, `addressName`, `usernames`, `indexName`, `debugDisplayTitle`, `displayLetters`, `profileImageRepresentations`, `smallProfileImage`, `largeProfileImage`, `isDeleted`, `isScam`, `isFake`, `isVerified`, `isPremium`, `isSubscription`, `isService`, `nameColor`, `verificationIconFileId`, `profileColor`, `effectiveProfileColor`, `emojiStatus`, `backgroundEmojiId`, `profileBackgroundEmojiId`, and (via `LocalizedPeerData/Sources/PeerTitle.swift`) `compactDisplayTitle`, `displayTitle(strings:displayOrder:)`. **Not** forwarded: Peer-specific members like `isCopyProtectionEnabled`, `hasPermission(_:)`, `hasBannedPermission(_:)`, `isDeleted` on user (WAIT: yes forwarded). **Internal helper bodies do not access any non-forwarded Peer members** — all their concrete-type work happens via `as? TelegramX`, which is enum-rewrite territory. Confirmed by reading helper bodies (PeerInfoData.swift:2255–2670).
### Helper call sites inventory (21 sites across 10 files)
Running command:
```bash
grep -rn "\bcanEditPeerInfo\b\|\bavailableActionsForMemberOfPeer\b\|\bpeerInfoHeaderActionButtons\b\|\bpeerInfoHeaderButtons\b\|\bpeerInfoCanEdit\b\|\bpeerInfoIsChatMuted\b" submodules/ --include="*.swift" | grep -v PeerInfoData.swift
```
All 21 call sites:
| # | File | Line | Current arg | Peer var origin | Action |
|---|------|------|-------------|-----------------|--------|
| 1 | `PeerInfoHeaderNode.swift` | 548 | `peer: peer` | method param `peer: Peer?` | ADD-WRAP: `peer: peer.flatMap(EnginePeer.init)` |
| 2 | `PeerInfoHeaderNode.swift` | 549 | `peer: peer` | same | ADD-WRAP |
| 3 | `PeerInfoHeaderNode.swift` | 2361 | `peer: peer` | same | ADD-WRAP |
| 4 | `PeerInfoEditingAvatarNode.swift` | 66 | `peer: peer` | method param `peer: Peer?` (unwrapped via `guard let peer = peer`) | ADD-WRAP: `peer: EnginePeer(peer)` (peer is non-optional `Peer` here) |
| 5 | `PeerInfoEditingAvatarOverlayNode.swift` | 85 | `peer: peer` | method param `peer: Peer?` (unwrapped via `guard let peer = peer`) | ADD-WRAP: `peer: EnginePeer(peer)` |
| 6 | `PeerInfoHeaderEditingContentNode.swift` | 59 | `peer: peer` | method param `peer: Peer?` | ADD-WRAP: `peer: peer.flatMap(EnginePeer.init)` |
| 7 | `PeerInfoHeaderEditingContentNode.swift` | 88 | `peer: peer` | same | ADD-WRAP |
| 8 | `PeerInfoHeaderEditingContentNode.swift` | 93 | `peer: peer` | same | ADD-WRAP |
| 9 | `PeerInfoHeaderEditingContentNode.swift` | 159 | `peer: peer` | same | ADD-WRAP |
| 10 | `PeerInfoHeaderEditingContentNode.swift` | 162 | `peer: peer` | same | ADD-WRAP |
| 11 | `PeerInfoScreenAvatarSetup.swift` | 435 | `peer: peer._asPeer()` | `peer = data.peer` (EnginePeer unwrapped) | DROP: `peer: peer` |
| 12 | `PeerInfoScreenPerformButtonAction.swift` | 62 | `peer: self.data?.peer?._asPeer()` | `self.data?.peer` is `EnginePeer?` | DROP: `peer: self.data?.peer` |
| 13 | `PeerInfoScreenPerformButtonAction.swift` | 397 | `peer: peer._asPeer()` | `peer = data.peer` unwrapped at line 381 | DROP: `peer: peer` |
| 14 | `PeerInfoScreenPerformButtonAction.swift` | 398 | `peer: peer._asPeer()` | same | DROP: `peer: peer` |
| 15 | `PeerInfoScreenOpenMember.swift` | 19 | `peer: enclosingPeer._asPeer()` | `enclosingPeer = self.data?.peer` unwrapped at line 14 | DROP: `peer: enclosingPeer` |
| 16 | `PeerInfoScreen.swift` | 1905 | `peer: group` | `group: TelegramGroup` from `if case let .legacyGroup(group) = data.peer` | CONVERT: `peer: data.peer` |
| 17 | `PeerInfoScreen.swift` | 1961 | `peer: channel` | `channel: TelegramChannel` from `if case let .channel(channel) = data.peer` | CONVERT: `peer: data.peer` |
| 18 | `PeerInfoScreen.swift` | 5857 | `peer: self.data?.peer?._asPeer()` | `self.data?.peer` is `EnginePeer?` | DROP: `peer: self.data?.peer` |
| 19 | `PeerInfoProfileItems.swift` | 853 | `peer: peer._asPeer()` | `peer = data.peer` unwrapped at line 821 | DROP: `peer: peer` |
| 20 | `PeerInfoScreenMemberItem.swift` | 178 | `peer: item.enclosingPeer` | `item.enclosingPeer: Peer` (stored raw) | ADD-WRAP: `peer: EnginePeer(item.enclosingPeer)` |
| 21 | `PeerInfoMembersPane.swift` | 139 | `peer: enclosingPeer` | `enclosingPeer: Peer` (local raw) | ADD-WRAP: `peer: EnginePeer(enclosingPeer)` |
**Summary:** 7 DROPs (sites 11–15, 18, 19), 10 ADD-WRAPs (1–10, 20, 21 = 12 total ADDs), 2 CONVERTs (16, 17 — from concrete-type arg to whole-EnginePeer; no wrap delta but simpler/safer).
### `is TelegramX` scan on helper bodies
Only `peerInfoIsChatMuted` has them (PeerInfoData.swift:2641, 2643). Rewrite pattern: `if peer is TelegramUser` → `if case .user = peer`, `else if peer is TelegramGroup` → `else if case .legacyGroup = peer`.
No `is TelegramX` checks exist at call sites for these specific helpers (wave-42 would have caught them since call-site `data.peer` is already `EnginePeer?`).
---
## File Structure
All edits within `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/`:
**Modify (helper definitions):**
- `PeerInfoData.swift:2265–2670` — 6 helper signatures + bodies
**Modify (call sites):**
- `PeerInfoScreen.swift` (3 sites: 1905, 1961, 5857)
- `PeerInfoHeaderNode.swift` (3 sites: 548, 549, 2361)
- `PeerInfoEditingAvatarNode.swift` (1 site: 66)
- `PeerInfoEditingAvatarOverlayNode.swift` (1 site: 85)
- `PeerInfoHeaderEditingContentNode.swift` (5 sites: 59, 88, 93, 159, 162)
- `PeerInfoScreenAvatarSetup.swift` (1 site: 435)
- `PeerInfoScreenPerformButtonAction.swift` (3 sites: 62, 397, 398)
- `PeerInfoScreenOpenMember.swift` (1 site: 19)
- `PeerInfoProfileItems.swift` (1 site: 853)
- `ListItems/PeerInfoScreenMemberItem.swift` (1 site: 178)
- `Panes/PeerInfoMembersPane.swift` (1 site: 139)
Total: 10 files modified (PeerInfoData.swift counts once).
---
### Task 1: Migrate the six helper signatures and bodies in `PeerInfoData.swift`
**Files:**
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoData.swift:2265–2670`
- [ ] **Step 1: Migrate `canEditPeerInfo` (line 2265).** Signature: `peer: Peer?` → `peer: EnginePeer?`. Body rewrites:
```swift
// before (line 2269-2287)
if let user = peer as? TelegramUser, let botInfo = user.botInfo {
return botInfo.flags.contains(.canEdit)
} else if let channel = peer as? TelegramChannel {
if let threadData = threadData {
if chatLocation.threadId == 1 {
return false
}
if channel.hasPermission(.manageTopics) {
return true
}
if threadData.author == context.account.peerId {
return true
}
} else {
if channel.hasPermission(.changeInfo) {
return true
}
}
} else if let group = peer as? TelegramGroup {
switch group.role {
case .admin, .creator:
return true
case .member:
break
}
if !group.hasBannedPermission(.banChangeInfo) {
return true
}
}
// after
if case let .user(user) = peer, let botInfo = user.botInfo {
return botInfo.flags.contains(.canEdit)
} else if case let .channel(channel) = peer {
if let threadData = threadData {
if chatLocation.threadId == 1 {
return false
}
if channel.hasPermission(.manageTopics) {
return true
}
if threadData.author == context.account.peerId {
return true
}
} else {
if channel.hasPermission(.changeInfo) {
return true
}
}
} else if case let .legacyGroup(group) = peer {
switch group.role {
case .admin, .creator:
return true
case .member:
break
}
if !group.hasBannedPermission(.banChangeInfo) {
return true
}
}
```
The `if context.account.peerId == peer?.id` line (2266) stays identical (`.id` is forwarded by `EnginePeer`).
- [ ] **Step 2: Migrate `availableActionsForMemberOfPeer` (line 2314).** Signature: `peer: Peer?` → `peer: EnginePeer?`. Body rewrites — four `peer as? TelegramChannel/TelegramGroup` sites become `case let .channel/.legacyGroup` patterns:
```swift
// Line 2320: if let channel = peer as? TelegramChannel
// → : if case let .channel(channel) = peer
// Line 2324: } else if let group = peer as? TelegramGroup {
// → : } else if case let .legacyGroup(group) = peer {
// Line 2330: if let channel = peer as? TelegramChannel
// → : if case let .channel(channel) = peer
// Line 2374: } else if let group = peer as? TelegramGroup {
// → : } else if case let .legacyGroup(group) = peer {
```
The `if peer == nil` check (line 2317) stays identical (Optional == nil works on EnginePeer? too).
- [ ] **Step 3: Migrate `peerInfoHeaderActionButtons` (line 2434).** Signature: `peer: Peer?` → `peer: EnginePeer?`. Single body rewrite at line 2436:
```swift
// before
if !isContact && !isSecretChat, let user = peer as? TelegramUser, user.botInfo == nil {
// after
if !isContact && !isSecretChat, case let .user(user) = peer, user.botInfo == nil {
```
- [ ] **Step 4: Migrate `peerInfoHeaderButtons` (line 2447).** Signature: `peer: Peer?` → `peer: EnginePeer?`. Three body rewrites:
```swift
// Line 2449: if let user = peer as? TelegramUser {
// → : if case let .user(user) = peer {
// Line 2483: } else if let channel = peer as? TelegramChannel {
// → : } else if case let .channel(channel) = peer {
// Line 2558: } else if let group = peer as? TelegramGroup {
// → : } else if case let .legacyGroup(group) = peer {
```
- [ ] **Step 5: Migrate `peerInfoCanEdit` (line 2585).** Signature: `peer: Peer?` → `peer: EnginePeer?`. Three body rewrites. Note: original shadows `peer` inside each branch (`let peer = peer as? TelegramX`). Rewrite preserves the shadowing via `case let`:
```swift
// Line 2586: if let user = peer as? TelegramUser {
// → : if case let .user(user) = peer {
// Line 2597: } else if let peer = peer as? TelegramChannel {
// → : } else if case let .channel(peer) = peer {
// (intentional shadow of outer `peer` with inner `peer: TelegramChannel` — preserved)
// Line 2618: } else if let peer = peer as? TelegramGroup {
// → : } else if case let .legacyGroup(peer) = peer {
```
- [ ] **Step 6: Migrate `peerInfoIsChatMuted` (line 2633).** Outer signature: `peer: Peer?` → `peer: EnginePeer?`. Inner function signature (line 2634) also migrates: `func isPeerMuted(peer: Peer?, ...)` → `func isPeerMuted(peer: EnginePeer?, ...)`. Body rewrites inside the inner function (line 2641–2651):
```swift
// before (line 2641)
if peer is TelegramUser {
peerIsMuted = !globalNotificationSettings.privateChats.enabled
} else if peer is TelegramGroup {
peerIsMuted = !globalNotificationSettings.groupChats.enabled
} else if let channel = peer as? TelegramChannel {
switch channel.info {
case .group:
peerIsMuted = !globalNotificationSettings.groupChats.enabled
case .broadcast:
peerIsMuted = !globalNotificationSettings.channels.enabled
}
}
// after
if case .user = peer {
peerIsMuted = !globalNotificationSettings.privateChats.enabled
} else if case .legacyGroup = peer {
peerIsMuted = !globalNotificationSettings.groupChats.enabled
} else if case let .channel(channel) = peer {
switch channel.info {
case .group:
peerIsMuted = !globalNotificationSettings.groupChats.enabled
case .broadcast:
peerIsMuted = !globalNotificationSettings.channels.enabled
}
}
```
The outer `if let peer = peer` (line 2640) stays unchanged (Optional binding works on EnginePeer?).
The inner `peerInfoIsChatMuted` body (line 2659–2669) calls `isPeerMuted(peer: peer, ...)` with the outer `peer` (now EnginePeer?) — works without change because inner signature now matches.
- [ ] **Step 7: Re-read PeerInfoData.swift lines 2265–2670 and visually verify no `as? TelegramX` or `is TelegramX` patterns remain.**
Run: `grep -n "as? TelegramUser\|as? TelegramChannel\|as? TelegramGroup\|is TelegramUser\|is TelegramChannel\|is TelegramGroup" submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoData.swift | awk -F: '$2 >= 2265 && $2 <= 2670'`
Expected: empty output.
---
### Task 2: Update call sites — DROPs (7 sites)
**Files:**
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreenAvatarSetup.swift:435`
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreenPerformButtonAction.swift:62,397,398`
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreenOpenMember.swift:19`
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreen.swift:5857`
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoProfileItems.swift:853`
- [ ] **Step 1: DROP at `PeerInfoScreenAvatarSetup.swift:435`.**
```swift
// before
guard let data = self.controllerNode.data, let peer = data.peer, mode != .generic || canEditPeerInfo(context: self.context, peer: peer._asPeer(), chatLocation: self.chatLocation, threadData: data.threadData) else {
// after
guard let data = self.controllerNode.data, let peer = data.peer, mode != .generic || canEditPeerInfo(context: self.context, peer: peer, chatLocation: self.chatLocation, threadData: data.threadData) else {
```
- [ ] **Step 2: DROP at `PeerInfoScreenPerformButtonAction.swift:62`.**
```swift
// before
let chatIsMuted = peerInfoIsChatMuted(peer: self.data?.peer?._asPeer(), peerNotificationSettings: self.data?.peerNotificationSettings, threadNotificationSettings: self.data?.threadNotificationSettings, globalNotificationSettings: self.data?.globalNotificationSettings)
// after
let chatIsMuted = peerInfoIsChatMuted(peer: self.data?.peer, peerNotificationSettings: self.data?.peerNotificationSettings, threadNotificationSettings: self.data?.threadNotificationSettings, globalNotificationSettings: self.data?.globalNotificationSettings)
```
- [ ] **Step 3: DROP at `PeerInfoScreenPerformButtonAction.swift:397 and :398` (peerInfoHeaderButtons, two lines, same pattern `peer: peer._asPeer()` → `peer: peer`).**
Use Edit with `replace_all=true` on the substring `peer: peer._asPeer(), cachedData: data.cachedData` — this exact form appears exactly twice in the file (lines 397, 398), both targets.
```swift
// before (at both 397 and 398)
peerInfoHeaderButtons(peer: peer._asPeer(), cachedData: data.cachedData, isOpenedFromChat: ...
// after
peerInfoHeaderButtons(peer: peer, cachedData: data.cachedData, isOpenedFromChat: ...
```
Verification after edit:
```bash
grep -n "_asPeer()" submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreenPerformButtonAction.swift
```
Expected: empty (all three DROPs done).
- [ ] **Step 4: DROP at `PeerInfoScreenOpenMember.swift:19`.**
```swift
// before
let actions = availableActionsForMemberOfPeer(accountPeerId: self.context.account.peerId, peer: enclosingPeer._asPeer(), member: member)
// after
let actions = availableActionsForMemberOfPeer(accountPeerId: self.context.account.peerId, peer: enclosingPeer, member: member)
```
- [ ] **Step 5: DROP at `PeerInfoScreen.swift:5857`.**
```swift
// before
} else if peerInfoCanEdit(peer: self.data?.peer?._asPeer(), chatLocation: self.chatLocation, threadData: self.data?.threadData, cachedData: self.data?.cachedData, isContact: self.data?.isContact) {
// after
} else if peerInfoCanEdit(peer: self.data?.peer, chatLocation: self.chatLocation, threadData: self.data?.threadData, cachedData: self.data?.cachedData, isContact: self.data?.isContact) {
```
- [ ] **Step 6: DROP at `PeerInfoProfileItems.swift:853`.**
Only the `availableActionsForMemberOfPeer` call — the sibling `enclosingPeer: peer._asPeer()` at line 852 is NOT a helper-migration target (it's `PeerInfoScreenMemberItem.enclosingPeer: Peer`, unchanged in this wave).
```swift
// before (line 853)
let actions = availableActionsForMemberOfPeer(accountPeerId: context.account.peerId, peer: peer._asPeer(), member: member)
// after
let actions = availableActionsForMemberOfPeer(accountPeerId: context.account.peerId, peer: peer, member: member)
```
---
### Task 3: Update call sites — CONVERTs (2 sites in PeerInfoScreen.swift)
**Files:**
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreen.swift:1905,1961`
At these sites the helper arg is currently a concrete `TelegramGroup` / `TelegramChannel` extracted via case pattern. After migration the helper takes `EnginePeer?`, so pass `data.peer` directly — the helper re-does the pattern match internally, semantics preserved.
- [ ] **Step 1: CONVERT at `PeerInfoScreen.swift:1905`.**
```swift
// before
} else if case let .legacyGroup(group) = data.peer, canEditPeerInfo(context: strongSelf.context, peer: group, chatLocation: chatLocation, threadData: data.threadData) {
// after
} else if case let .legacyGroup(group) = data.peer, canEditPeerInfo(context: strongSelf.context, peer: data.peer, chatLocation: chatLocation, threadData: data.threadData) {
```
`group` stays bound because the body below still uses it. Only the helper arg changes.
- [ ] **Step 2: CONVERT at `PeerInfoScreen.swift:1961`.**
```swift
// before
} else if case let .channel(channel) = data.peer, canEditPeerInfo(context: strongSelf.context, peer: channel, chatLocation: strongSelf.chatLocation, threadData: data.threadData) {
// after
} else if case let .channel(channel) = data.peer, canEditPeerInfo(context: strongSelf.context, peer: data.peer, chatLocation: strongSelf.chatLocation, threadData: data.threadData) {
```
---
### Task 4: Update call sites — ADD-WRAPs in internal-update methods (10 sites in 4 files)
These files' internal `.update(peer: Peer?, ...)` methods are NOT migrated in this wave (scope: helpers only). Each helper call inside bridges `peer` (raw `Peer?`) to `EnginePeer?` via `.flatMap(EnginePeer.init)`, or — where `peer` has already been unwrapped to non-optional `Peer` — via `EnginePeer(peer)`.
**Files:**
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoHeaderNode.swift:548,549,2361`
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoEditingAvatarNode.swift:66`
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoEditingAvatarOverlayNode.swift:85`
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoHeaderEditingContentNode.swift:59,88,93,159,162`
- [ ] **Step 1: ADD-WRAPs at `PeerInfoHeaderNode.swift:548,549,2361`.** At lines 548, 549, the local `peer` is the raw `Peer?` method parameter (line 496). At line 2361 likewise.
```swift
// before (line 548)
let actionButtonKeys: [PeerInfoHeaderButtonKey] = (self.isSettings || self.isMyProfile) ? [] : peerInfoHeaderActionButtons(peer: peer, isSecretChat: isSecretChat, isContact: isContact)
// after
let actionButtonKeys: [PeerInfoHeaderButtonKey] = (self.isSettings || self.isMyProfile) ? [] : peerInfoHeaderActionButtons(peer: peer.flatMap(EnginePeer.init), isSecretChat: isSecretChat, isContact: isContact)
```
```swift
// before (line 549)
let buttonKeys: [PeerInfoHeaderButtonKey] = (self.isSettings || self.isMyProfile) ? [] : peerInfoHeaderButtons(peer: peer, cachedData: cachedData, ...)
// after
let buttonKeys: [PeerInfoHeaderButtonKey] = (self.isSettings || self.isMyProfile) ? [] : peerInfoHeaderButtons(peer: peer.flatMap(EnginePeer.init), cachedData: cachedData, ...)
```
```swift
// before (line 2361)
let chatIsMuted = peerInfoIsChatMuted(peer: peer, peerNotificationSettings: peerNotificationSettings, threadNotificationSettings: threadNotificationSettings, globalNotificationSettings: globalNotificationSettings)
// after
let chatIsMuted = peerInfoIsChatMuted(peer: peer.flatMap(EnginePeer.init), peerNotificationSettings: peerNotificationSettings, threadNotificationSettings: threadNotificationSettings, globalNotificationSettings: globalNotificationSettings)
```
- [ ] **Step 2: ADD-WRAP at `PeerInfoEditingAvatarNode.swift:66`.** Here `peer` is non-optional `Peer` (unwrapped at line 62: `guard let peer = peer else { return }`). Use `EnginePeer(peer)`.
```swift
// before
let canEdit = canEditPeerInfo(context: self.context, peer: peer, chatLocation: chatLocation, threadData: threadData)
// after
let canEdit = canEditPeerInfo(context: self.context, peer: EnginePeer(peer), chatLocation: chatLocation, threadData: threadData)
```
- [ ] **Step 3: ADD-WRAP at `PeerInfoEditingAvatarOverlayNode.swift:85`.** Same shape — `peer` is non-optional `Peer` (unwrapped at line 64).
```swift
// before
if canEditPeerInfo(context: self.context, peer: peer, chatLocation: chatLocation, threadData: threadData)
// after
if canEditPeerInfo(context: self.context, peer: EnginePeer(peer), chatLocation: chatLocation, threadData: threadData)
```
- [ ] **Step 4: ADD-WRAPs at `PeerInfoHeaderEditingContentNode.swift:59,88,93,159,162`.** Here `peer` is the method's `peer: Peer?` parameter (line 52). Five identical bridge forms.
For each of lines 59, 88, 93, 159, 162, replace `peer: peer` (inside `canEditPeerInfo(... peer: peer, ...)`) with `peer: peer.flatMap(EnginePeer.init)`.
The simplest approach: issue five separate Edit calls, each scoped to a unique surrounding substring. Example:
```swift
// before (line 59)
if canEditPeerInfo(context: self.context, peer: peer, chatLocation: chatLocation, threadData: threadData) {
// after
if canEditPeerInfo(context: self.context, peer: peer.flatMap(EnginePeer.init), chatLocation: chatLocation, threadData: threadData) {
```
Note line 59's trailing double-space before `{` in the original — preserve it.
Lines 88, 93, 159 share an identical surrounding substring `if canEditPeerInfo(context: self.context, peer: peer, chatLocation: chatLocation, threadData: threadData) {` (no trailing double-space, no `|| isEditableBot`). To avoid collision with line 59, use `replace_all=true` on THIS exact string (matches 88, 93 — wait, 159 uses `isEnabled = canEditPeerInfo(...)`, different prefix). Safer plan: one Edit per line, each with enough surrounding context to be unique. Verify uniqueness after each edit with grep.
Line 88's surrounding context: inside `if let _ = peer as? TelegramGroup {` branch — preceded by `fieldKeys.append(.title)`.
Line 93's surrounding context: inside `if let _ = peer as? TelegramChannel {` branch — preceded by `fieldKeys.append(.title)`. Same inner phrase as 88 — so `fieldKeys.append(.title)\n if canEditPeerInfo...` appears twice. Use line-specific context (preceding `else if let _ = peer as?` token).
Line 159: `isEnabled = canEditPeerInfo(context: self.context, peer: peer, chatLocation: chatLocation, threadData: threadData)` (no trailing text).
Line 162: `isEnabled = canEditPeerInfo(context: self.context, peer: peer, chatLocation: chatLocation, threadData: threadData) || isEditableBot`. Unique — contains ` || isEditableBot`.
Recommended: five sequential Edits with explicit line disambiguation via surrounding context. Do not bulk-replace-all — the identical `peer: peer, chatLocation: chatLocation, threadData: threadData)` substring appears at all five sites but their line-specific surroundings differ.
Verification after all five edits:
```bash
grep -c "peer: peer," submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoHeaderEditingContentNode.swift
```
Expected: 0 (no unmigrated call sites remain; other `peer:` occurrences in the file are either type annotations or at the method signature, which uses `peer: Peer?` not `peer: peer`).
---
### Task 5: Update call sites — ADD-WRAPs at raw-`Peer` member-item sites (2 sites)
**Files:**
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/ListItems/PeerInfoScreenMemberItem.swift:178`
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/Panes/PeerInfoMembersPane.swift:139`
At these sites `enclosingPeer` is non-optional `Peer` (raw, stored on the item / local). Wrap with `EnginePeer(...)`.
- [ ] **Step 1: ADD-WRAP at `PeerInfoScreenMemberItem.swift:178`.**
```swift
// before
let actions = availableActionsForMemberOfPeer(accountPeerId: item.context.accountPeerId, peer: item.enclosingPeer, member: item.member)
// after
let actions = availableActionsForMemberOfPeer(accountPeerId: item.context.accountPeerId, peer: EnginePeer(item.enclosingPeer), member: item.member)
```
- [ ] **Step 2: ADD-WRAP at `PeerInfoMembersPane.swift:139`.**
```swift
// before
let actions = availableActionsForMemberOfPeer(accountPeerId: context.account.peerId, peer: enclosingPeer, member: member)
// after
let actions = availableActionsForMemberOfPeer(accountPeerId: context.account.peerId, peer: EnginePeer(enclosingPeer), member: member)
```
---
### Task 6: Build and iterate
- [ ] **Step 1: Full project build with `--continueOnError` to surface all errors at once.**
```bash
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 \
--configuration=debug_sim_arm64 --continueOnError
```
Expected: likely 2-iteration convergence. Budget up to iteration 3.
Likely categories of residual errors:
1. **Missed call sites** — grep-miss from planning. Remediate by adding `.flatMap(EnginePeer.init)` or `EnginePeer(...)` as appropriate.
2. **Missed `as? TelegramX` / `is TelegramX` inside helper bodies** — Swift compiler error "cannot convert value of type 'EnginePeer?' to expected argument type 'Peer?'" or warning "'is' test is always false". Fix with `case` pattern.
3. **Optional-lifting edge cases** — `if case let .user(user) = peer` may fail if Swift interprets `peer` as non-optional. If so, rewrite as `if let peer, case let .user(user) = peer`.
4. **Unused binding warnings** — e.g. `if case let .user(user) = peer` where `user` isn't used inside that branch. Swift's `-warnings-as-errors` (658/665 submodule BUILDs) promotes these. Rewrite as `if case .user = peer`.
5. **Unused variable `peer` or `group`/`channel` at CONVERT sites 16, 17** — lines 1905/1961 bind `group`/`channel` in the `case let` pattern; if the body body doesn't use it, Swift emits "value 'group' was never used" which `-warnings-as-errors` promotes to error. Since the body below DOES use them (updatePeerTitle(peerId: group.id, ...)` etc.), this should not trigger — but verify.
- [ ] **Step 2: For each error category above, apply the correct fix in-place and rebuild. Iterate until green.**
- [ ] **Step 3: After build is green, run the post-migration grep audit:**
```bash
# Should be empty — no _asPeer() bridges at helper call sites
grep -rn "canEditPeerInfo(.*_asPeer\|peerInfoIsChatMuted(.*_asPeer\|peerInfoHeaderButtons(.*_asPeer\|peerInfoHeaderActionButtons(.*_asPeer\|peerInfoCanEdit(.*_asPeer\|availableActionsForMemberOfPeer(.*_asPeer" submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/
# Should be empty — no concrete-type casts against peer param in helper bodies
grep -nE "as\?\s+TelegramUser|as\?\s+TelegramChannel|as\?\s+TelegramGroup|\bis\s+TelegramUser\b|\bis\s+TelegramChannel\b|\bis\s+TelegramGroup\b" submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoData.swift | awk -F: '$2 >= 2265 && $2 <= 2670'
```
Expected: both empty.
---
### Task 7: Commit
- [ ] **Step 1: Verify working tree only contains wave-43 edits + pre-existing WIP.**
```bash
git status --short
```
Expected (pre-existing WIP, NOT to be staged):
```
m build-system/bazel-rules/sourcekit-bazel-bsp
M submodules/TelegramUI/Sources/ChatMessageTransitionNode.swift
?? build-system/tulsi/
?? submodules/TgVoip/
?? third-party/libx264/
```
Plus wave-43 edits (all under `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/`):
```
M submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoData.swift
M submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreen.swift
M submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoHeaderNode.swift
M submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoEditingAvatarNode.swift
M submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoEditingAvatarOverlayNode.swift
M submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoHeaderEditingContentNode.swift
M submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreenAvatarSetup.swift
M submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreenPerformButtonAction.swift
M submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreenOpenMember.swift
M submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoProfileItems.swift
M submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/ListItems/PeerInfoScreenMemberItem.swift
M submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/Panes/PeerInfoMembersPane.swift
```
- [ ] **Step 2: Explicitly stage only the wave-43 files (not the WIP).**
```bash
git add \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoData.swift \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreen.swift \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoHeaderNode.swift \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoEditingAvatarNode.swift \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoEditingAvatarOverlayNode.swift \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoHeaderEditingContentNode.swift \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreenAvatarSetup.swift \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreenPerformButtonAction.swift \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreenOpenMember.swift \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoProfileItems.swift \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/ListItems/PeerInfoScreenMemberItem.swift \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/Panes/PeerInfoMembersPane.swift \
docs/superpowers/plans/2026-04-24-peerinfoscreen-helpers-engine-peer-migration.md
```
- [ ] **Step 3: Commit.**
Use a HEREDOC for the message:
```bash
git commit -m "$(cat <<'EOF'
Postbox -> TelegramEngine wave 43
Migrate six PeerInfoScreen helpers (canEditPeerInfo,
availableActionsForMemberOfPeer, peerInfoHeaderActionButtons,
peerInfoHeaderButtons, peerInfoCanEdit, peerInfoIsChatMuted) from
`peer: Peer?` to `peer: EnginePeer?`. Internal `as? TelegramX` /
`is TelegramX` patterns rewritten to `case let .x` / `case .x` on
EnginePeer enum. All 21 call sites updated in the same commit: 7
`._asPeer()` bridges installed by wave 42 dropped; 12
`.flatMap(EnginePeer.init)` / `EnginePeer(...)` wraps added at sites
whose enclosing methods still take raw Peer?; 2 concrete-type args
converted to pass the whole EnginePeer value.
All edits within submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/.
No new engine typealiases. No TelegramCore changes.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 4: Verify commit.**
```bash
git log --oneline -1
git show --stat HEAD
```
Expected: one commit, ~10 files changed, clean diff.
---
## Self-review checklist (run before handoff)
**Spec coverage:**
- All 6 helper signatures migrated (Task 1 steps 1–6). ✓
- All 21 call sites touched (Tasks 2–5). ✓
- Build iteration explicit (Task 6). ✓
- Commit explicit (Task 7). ✓
**Type consistency:**
- Helper signatures all `peer: EnginePeer?` (consistent). ✓
- Call-site transforms: DROP/ADD/CONVERT actions match the inventory table. ✓
- `EnginePeer.init` constructor used both as `.flatMap(EnginePeer.init)` (Peer? → EnginePeer?) and `EnginePeer(...)` (Peer → EnginePeer) — both are valid (construction overloaded on EnginePeer extension at `TelegramCore/TelegramEngine/Peers/Peer.swift:564`). ✓
**Placeholder scan:**
- No "TBD" / "handle appropriately" / "similar to Task N" language — every step has its concrete code. ✓
**Risks flagged:**
- Wave-41 lesson: foundational-type migrations rarely first-pass-clean. Budget 2 iterations. ✓
- Wave-41 lesson: `-warnings-as-errors` promotes always-false `is` checks and unused bindings to build errors. Task 6 step 1 calls these out explicitly. ✓
- Wave-42 lesson: `EnginePeer` doesn't forward every Peer property. Helper bodies were verified to access only `.id`, which IS forwarded; other property accesses were on concrete types (`TelegramChannel.hasPermission(...)` etc.) which remain on concrete types post-migration. No forwarding-gap remediation expected in helpers. ✓

164
docs/superpowers/plans/2026-04-24-peerinfoscreendata-peer-engine-peer-migration.md
View file

@ -1,164 +0,0 @@
# Wave 42 plan: `PeerInfoScreenData.peer: Peer? → EnginePeer?`
Date: 2026-04-24
Preceding waves: 41 (`RenderedChannelParticipant.peer`), 40 (`makeChatQrCodeScreen`/`makeChatRecentActionsController`), 39 (`makePeerInfoController`)
Scope (confirmed with user): only `PeerInfoScreenData.peer`. Sibling fields (`chatPeer`, `savedMessagesPeer`, `linkedDiscussionPeer`, `linkedMonoforumPeer`) are follow-up-wave candidates.
## Change target
File: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoData.swift`
- L386: `let peer: Peer?` → `let peer: EnginePeer?`
- L442: `peer: Peer?,` → `peer: EnginePeer?,`
- Store unchanged (`self.peer = peer`)
## Construction sites (5, all in PeerInfoData.swift)
| Line | Current `peer:` arg | Rewrite |
|------|---------------------|---------|
| 1027 | `peer: peer` (local, `Peer?` from `peerView.peers[peerId]`) | `peer: peer.flatMap(EnginePeer.init)` |
| 1100 | `peer: nil` | unchanged |
| 1620 | `peer: peer` (local, `Peer?` from `peerView.peers[userPeerId]`) | `peer: peer.flatMap(EnginePeer.init)` |
| 1867 | `peer: peerView.peers[peerId]` | `peer: peerView.peers[peerId].flatMap(EnginePeer.init)` |
| 2205 | `peer: peerView.peers[groupId]` | `peer: peerView.peers[groupId].flatMap(EnginePeer.init)` |
## Consumer migration patterns (across 18 files, ~114 `data.peer` accesses)
### Pattern A — as-cast → enum pattern match (~20 sites)
```swift
// before
if let user = data.peer as? TelegramUser, user.botInfo == nil { ... }
// after
if case let .user(user) = data.peer, user.botInfo == nil { ... }
```
Scope both sides consistently. A cast inside a larger `guard let ..., let user = ... as? TelegramUser else { return }` becomes `guard ..., case let .user(user) = data.peer else { return }`.
### Pattern B — `is TelegramXxx` check → enum case pattern (~5 sites)
The wave-41 lesson: `-warnings-as-errors` catches always-false `is` checks.
```swift
// before
if let peer = self.data?.peer, peer is TelegramChannel { ... }
if peer is TelegramGroup { ... }
// after
if case .channel = self.data?.peer { ... }
if case .legacyGroup = peer { ... }
```
`TelegramGroup` maps to `.legacyGroup`. `TelegramChannel` maps to `.channel`. `TelegramUser` maps to `.user`. `TelegramSecretChat` maps to `.secretChat`.
Known sites in PeerInfoScreen.swift (inventory): L3981, L4133, L4192, L4194 (and L7421 for `chatPeer`-bound — chatPeer stays raw, so L7421 is out of scope). Use repo grep on `PeerInfoScreen/Sources` with token `is Telegram(Channel|User|Group|SecretChat)` to catch other sites.
### Pattern C — existing `EnginePeer(peer)` wraps where `peer` was bound from `data.peer` — DROP (15+ sites)
```swift
// before
if let peer = self.data?.peer {
self.joinChannel(peer: EnginePeer(peer)) // wave-40 wrap
}
// after
if let peer = self.data?.peer {
self.joinChannel(peer: peer) // peer is now EnginePeer already
}
```
Care needed: only drop the wrap where the bound `peer` variable comes from `data.peer`. Wraps on `chatPeer`, `currentPeer`, `user` (bound via `as? TelegramUser`), `groupPeer`, or PeerView lookups stay. The lexical scope makes this judgeable.
Known drop sites (PeerInfoScreen.swift): 1331, 1339, 1346, 1561, 2353, 2405, 3409, 3459, 3624, 3747, 4306, 4573 (inner — review scope), 4623. PeerInfoHeaderNode.swift: 571, 1218, 2054 (if bound from data.peer). PeerInfoScreenOpenChat.swift: 25, 40, 51, 57, 80, 89, 115. Verify each by backtracking the `if let peer = ...` binding.
### Pattern D — helper call sites still taking `Peer?` (ADD-WRAP, ~10 sites)
`canEditPeerInfo`, `peerInfoIsChatMuted`, `peerInfoHeaderButtons`, `peerInfoHeaderActionButtons`, `peerInfoCanEdit`, `availableActionsForMemberOfPeer` all keep `peer: Peer?` in this wave. Call sites must bridge:
```swift
// before
peerInfoIsChatMuted(peer: self.data?.peer, ...)
// after
peerInfoIsChatMuted(peer: self.data?.peer?._asPeer(), ...)
```
Site count (from grep): PeerInfoHeaderNode.swift:548/549/2361, PeerInfoScreenAvatarSetup.swift:435, PeerInfoScreenPerformButtonAction.swift:62/397/398, PeerInfoEditingAvatarNode.swift:66, PeerInfoScreen.swift:1905/1961/5857, PeerInfoHeaderEditingContentNode.swift:59/88/93/159/162, PeerInfoEditingAvatarOverlayNode.swift:85. But the local `peer` at some of these is already narrowed via `as? TelegramUser` (now `case let .user(user)`); in that case the helper gets `user` (still `Peer`-conforming), no bridge needed. Bridge only where the raw `data.peer` flows into the helper.
These ADD-WRAP markers become ratchet-drops for a follow-up wave that migrates the helper signatures.
### Pattern E — `EnginePeer?` passed as `EnginePeer?` directly (DROP wraps on callback args)
Where `data.peer` feeds `makePeerInfoController(peer: EnginePeer)` / `chatInterfaceInteraction.openPeer(_ peer: EnginePeer, ...)` / `.peer(EnginePeer)` ChatLocation / `AvatarGalleryController(peer: EnginePeer)` / `makeChatQrCodeScreen(peer: EnginePeer)` / `makeChatRecentActionsController(peer: EnginePeer)` — drop the `EnginePeer(...)` wrap; pass directly.
### Pattern F — `EnginePeer(peer).displayTitle(...)` / `.compactDisplayTitle` usage (DROP wrap)
```swift
// before
EnginePeer(peer).displayTitle(strings: ..., displayOrder: ...)
// after (peer is now EnginePeer already)
peer.displayTitle(strings: ..., displayOrder: ...)
```
### Pattern G — `.isPremium` on `peer?` inside construction site (L1060, L1626, L1902, L2242)
`peerView.peers[peerId]?.isPremium` — `Peer` protocol exposes `isPremium`. But the construction site receives raw `Peer?` and then we wrap via `flatMap(EnginePeer.init)`. The `peer?.isPremium` in the same construction scope still refers to the *local* raw peer variable (type unchanged), not `self.peer`. **No change needed at construction sites for `.isPremium` accesses on the local raw `peer`.** Only change `.isPremium` accesses on `data.peer` (which is now `EnginePeer?`) — `EnginePeer.isPremium` exists.
## File-by-file plan
1. **PeerInfoData.swift** — declaration + init + 5 constructions. Also review L1529 (`peerView.peers[peerView.peerId] is TelegramUser`) — OUT OF SCOPE (not `data.peer`); don't touch. Helper functions L2265/2314/2434/2447/2585/2633 stay `peer: Peer?` — DO NOT TOUCH.
2. **PeerInfoScreen.swift** — largest consumer, ~70+ sites. Walk every `data.peer` / `data?.peer` / `self.data?.peer` / `self.data.peer`. Apply A/B/C/E/F patterns. For `if let peer = data.peer` bindings, subsequent uses of `peer` now have type `EnginePeer` — drop wraps on those uses.
3. **PeerInfoScreenOpenChat.swift, PeerInfoScreenOpenBio.swift, PeerInfoScreenOpenMember.swift, PeerInfoScreenOpenPeerInfoContextMenu.swift, PeerInfoScreenOpenUsername.swift, PeerInfoScreenCallActions.swift, PeerInfoScreenMessageActions.swift, PeerInfoScreenPerformButtonAction.swift, PeerInfoScreenAvatarSetup.swift, PeerInfoScreenSettingsActions.swift, PeerInfoScreenDisplayGiftsContextMenu.swift, PeerInfoScreenDisplayMediaGalleryContextMenu.swift** — various `data?.peer as? TelegramXxx` (A), helper bridges (D), wrap drops (C/E).
4. **PeerInfoPaneContainerNode.swift** — L1252 `as? TelegramChannel` (A).
5. **PeerInfoProfileItems.swift, PeerInfoSettingsItems.swift, ListItems/PeerInfoScreenPersonalChannelItem.swift** — `data.peer as? TelegramUser` style consumers (A).
6. **PeerInfoHeaderNode.swift, PeerInfoEditingAvatarNode.swift, PeerInfoEditingAvatarOverlayNode.swift, PeerInfoHeaderEditingContentNode.swift** — these files receive `peer` as a parameter (not directly `data.peer`). Only touch if a parameter type declared as `Peer?` is the field from `data.peer` being passed in; otherwise leave.
## Replace_all guidance (wave-41 lesson)
Several wraps repeat identically. Where a file has multiple identical `EnginePeer(peer)` expressions in scopes where `peer` is now `EnginePeer`, use `replace_all=true` on the unique full expression. BUT verify each such file has no same-pattern wrap where `peer` is still raw (chatPeer-bound, currentPeer-bound, etc.) — such wraps must survive.
Safer alternative: edit each site individually.
## Out of scope (enumerated)
- `PeerInfoScreenData.chatPeer`, `.savedMessagesPeer`, `.linkedDiscussionPeer`, `.linkedMonoforumPeer` — stay `Peer?`.
- Internal helpers `canEditPeerInfo` / `peerInfoIsChatMuted` / etc. — stay `peer: Peer?`.
- `peerView.peers[...]` access inside PeerInfoData.swift — stays raw `Peer?`.
- Any `is TelegramXxx` check on a non-`data.peer`-derived variable.
## Build methodology
1. Apply declaration + init + construction edits.
2. Apply consumer edits file by file.
3. `source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 --configuration=debug_sim_arm64 --continueOnError`
4. Iterate on errors. Budget: 2–4 iterations (wave-41 lesson: foundational-type property-access migrations are not first-pass-clean).
## Expected ratchet math
- Drops: 15+ wave-40 wraps, ~20 as-cast patterns collapsed, ~5 is-checks rewritten, several `EnginePeer(peer).displayTitle` wraps dropped.
- Adds: ~10 `?._asPeer()` helper bridges, 4 `flatMap(EnginePeer.init)` at construction.
- Net: ~15–25 bridges dropped.
## WIP interference check
Pre-existing WIP in tree (per memory):
- `submodules/TelegramUI/Sources/ChatMessageTransitionNode.swift` — modified, unrelated animation WIP. DO NOT TOUCH.
- `submodules/TgVoip/`, `third-party/libx264/`, `build-system/tulsi/` — untracked, unrelated.
- `build-system/bazel-rules/sourcekit-bazel-bsp` — submodule marker, unrelated.
Wave-42 files are all in `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/` — no overlap with WIP. Commit with explicit file list (wave-39/41 lesson).
## Post-commit followups
- Update `docs/superpowers/postbox-refactor-log.md` with "Wave 42 outcome".
- Update `memory/project_postbox_refactor_next_wave.md` with wave 43 candidates:
- Wave 42.x sibling: `PeerInfoScreenData.chatPeer` / `.savedMessagesPeer` / `.linkedDiscussionPeer` / `.linkedMonoforumPeer` as a bundle (same file, narrow blast radius).
- Wave 42.y: PeerInfo-internal helper signatures (drops the ~10 ADD-WRAP markers).
- Option 2 from wave-42 shortlist: `RenderedChannelParticipant.peers` dict.

395
docs/superpowers/plans/2026-04-24-peertokentitle-engine-peer-migration.md
View file

@ -1,395 +0,0 @@
# Postbox → TelegramEngine wave 37: `peerTokenTitle` peer parameter Peer → EnginePeer
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Migrate the private free function `peerTokenTitle(accountPeerId: PeerId, peer: Peer, strings:, nameDisplayOrder:)` in `submodules/TelegramUI/Sources/ContactMultiselectionController.swift` so `peer` is `EnginePeer`, dropping 5 `._asPeer()` bridges at call sites in the same file.
**Architecture:** Single-file, atomic, private-function refactor. No public API change, no BUILD-file touch, no cross-module effects. Function body simplifies `EnginePeer(peer).displayTitle(...)` → `peer.displayTitle(...)`.
**Tech Stack:** Swift, Bazel via `Make.py` wrapper, Telegram-iOS project conventions (see CLAUDE.md).
**Reference:** Spec `docs/superpowers/specs/2026-04-24-peertokentitle-engine-peer-migration-design.md`.
---
## File Structure
Only one file is touched:
- **Modify:** `submodules/TelegramUI/Sources/ContactMultiselectionController.swift`
- L21 — signature change (`peer: Peer` → `peer: EnginePeer`)
- L27 — body simplification (drop redundant `EnginePeer(...)` wrap)
- L171, L201, L386, L403, L748 — call-site bridge drops (`peer: peer._asPeer()` → `peer: peer`)
No files created. No files deleted. No BUILD files touched.
---
## Task 1: Pre-flight inventory verification
**Files:** None (grep-only).
- [ ] **Step 1: Confirm the function is private and single-file**
Run:
```bash
grep -rn "peerTokenTitle" submodules/ Telegram/ third-party/ --include="*.swift"
```
Expected: exactly 6 matches, all in `submodules/TelegramUI/Sources/ContactMultiselectionController.swift` — 1 definition at L21 and 5 call sites at L171, L201, L386, L403, L748.
If any match appears outside this file, **stop and re-evaluate scope**: the function may not actually be private or another file has copy-pasted the name.
- [ ] **Step 2: Confirm all 5 call sites currently use `._asPeer()`**
Run:
```bash
grep -n "peerTokenTitle(.*_asPeer())" submodules/TelegramUI/Sources/ContactMultiselectionController.swift
```
Expected: 5 matches, line numbers 171, 201, 386, 403, 748.
If the count is not 5, **stop and re-inventory** — a prior change may have shifted line numbers or altered a call site.
- [ ] **Step 3: Confirm no other `peerTokenTitle` overload exists**
Run:
```bash
grep -n "func peerTokenTitle" submodules/TelegramUI/Sources/ContactMultiselectionController.swift
```
Expected: exactly 1 match at line 21 (`private func peerTokenTitle(...)`).
- [ ] **Step 4: Confirm `EnginePeer.displayTitle(strings:displayOrder:)` exists**
Run:
```bash
grep -rn "func displayTitle(strings:" submodules/TelegramCore/Sources/TelegramEngine/ submodules/TelegramCore/Sources/SyncCore/
```
Expected: a match on `EnginePeer` extension exposing `displayTitle(strings: PresentationStrings, displayOrder: PresentationPersonNameOrder)`. (This is the method already called as `EnginePeer(peer).displayTitle(...)` at L27, so its existence is certain — this step just makes the dependency explicit.)
---
## Task 2: Edit the function signature and body
**Files:**
- Modify: `submodules/TelegramUI/Sources/ContactMultiselectionController.swift:21-29`
- [ ] **Step 1: Read the current function definition**
Read the file, lines 21–29. Current state:
```swift
private func peerTokenTitle(accountPeerId: PeerId, peer: Peer, strings: PresentationStrings, nameDisplayOrder: PresentationPersonNameOrder) -> String {
if peer.id == accountPeerId {
return strings.DialogList_SavedMessages
} else if peer.id.isReplies {
return strings.DialogList_Replies
} else {
return EnginePeer(peer).displayTitle(strings: strings, displayOrder: nameDisplayOrder)
}
}
```
- [ ] **Step 2: Apply the signature change**
Use Edit with:
- `old_string`:
```
private func peerTokenTitle(accountPeerId: PeerId, peer: Peer, strings: PresentationStrings, nameDisplayOrder: PresentationPersonNameOrder) -> String {
if peer.id == accountPeerId {
return strings.DialogList_SavedMessages
} else if peer.id.isReplies {
return strings.DialogList_Replies
} else {
return EnginePeer(peer).displayTitle(strings: strings, displayOrder: nameDisplayOrder)
}
}
```
- `new_string`:
```
private func peerTokenTitle(accountPeerId: PeerId, peer: EnginePeer, strings: PresentationStrings, nameDisplayOrder: PresentationPersonNameOrder) -> String {
if peer.id == accountPeerId {
return strings.DialogList_SavedMessages
} else if peer.id.isReplies {
return strings.DialogList_Replies
} else {
return peer.displayTitle(strings: strings, displayOrder: nameDisplayOrder)
}
}
```
Note: `accountPeerId: PeerId` stays as-is — `PeerId` is already the typealias for `EnginePeer.Id`. `peer.id.isReplies` works unchanged because `EnginePeer.Id` exposes `isReplies`.
---
## Task 3: Drop `._asPeer()` bridges at all 5 call sites
**Files:**
- Modify: `submodules/TelegramUI/Sources/ContactMultiselectionController.swift` (L171, L201, L386, L403, L748)
All 5 call sites have an identical argument fragment:
```
peer: peer._asPeer(),
```
…which must become:
```
peer: peer,
```
The surrounding context differs per site (two distinct `strings/nameDisplayOrder` chains, see below), so we handle the substitution in two batches.
- [ ] **Step 1: Replace sites L171, L201, L748 (use `strongSelf.presentationData.strings` / `strongSelf.presentationData.nameDisplayOrder` or `self.presentationData.strings` / `self.presentationData.nameDisplayOrder`)**
Three call sites share identical code but with different leading `accountPeerId` expressions. Apply them individually.
**L171 and L201 are identical** — both read:
```swift
return EditableTokenListToken(id: peer.id, title: peerTokenTitle(accountPeerId: params.context.account.peerId, peer: peer._asPeer(), strings: strongSelf.presentationData.strings, nameDisplayOrder: strongSelf.presentationData.nameDisplayOrder), fixedPosition: nil, subject: .peer(peer))
```
Use Edit with `replace_all=true`:
- `old_string`:
```
return EditableTokenListToken(id: peer.id, title: peerTokenTitle(accountPeerId: params.context.account.peerId, peer: peer._asPeer(), strings: strongSelf.presentationData.strings, nameDisplayOrder: strongSelf.presentationData.nameDisplayOrder), fixedPosition: nil, subject: .peer(peer))
```
- `new_string`:
```
return EditableTokenListToken(id: peer.id, title: peerTokenTitle(accountPeerId: params.context.account.peerId, peer: peer, strings: strongSelf.presentationData.strings, nameDisplayOrder: strongSelf.presentationData.nameDisplayOrder), fixedPosition: nil, subject: .peer(peer))
```
**L748** reads:
```swift
tokens.append(EditableTokenListToken(id: peer.id, title: peerTokenTitle(accountPeerId: self.context.account.peerId, peer: peer._asPeer(), strings: self.presentationData.strings, nameDisplayOrder: self.presentationData.nameDisplayOrder), fixedPosition: nil, subject: .peer(peer)))
```
Use Edit (no `replace_all` — this line is unique):
- `old_string`:
```
tokens.append(EditableTokenListToken(id: peer.id, title: peerTokenTitle(accountPeerId: self.context.account.peerId, peer: peer._asPeer(), strings: self.presentationData.strings, nameDisplayOrder: self.presentationData.nameDisplayOrder), fixedPosition: nil, subject: .peer(peer)))
```
- `new_string`:
```
tokens.append(EditableTokenListToken(id: peer.id, title: peerTokenTitle(accountPeerId: self.context.account.peerId, peer: peer, strings: self.presentationData.strings, nameDisplayOrder: self.presentationData.nameDisplayOrder), fixedPosition: nil, subject: .peer(peer)))
```
- [ ] **Step 2: Replace sites L386 and L403 (use `accountPeerId` local)**
**L386 and L403 are identical** — both read:
```swift
addedToken = EditableTokenListToken(id: peer.id, title: peerTokenTitle(accountPeerId: accountPeerId, peer: peer._asPeer(), strings: strongSelf.presentationData.strings, nameDisplayOrder: strongSelf.presentationData.nameDisplayOrder), fixedPosition: nil, subject: .peer(peer))
```
Use Edit with `replace_all=true`:
- `old_string`:
```
addedToken = EditableTokenListToken(id: peer.id, title: peerTokenTitle(accountPeerId: accountPeerId, peer: peer._asPeer(), strings: strongSelf.presentationData.strings, nameDisplayOrder: strongSelf.presentationData.nameDisplayOrder), fixedPosition: nil, subject: .peer(peer))
```
- `new_string`:
```
addedToken = EditableTokenListToken(id: peer.id, title: peerTokenTitle(accountPeerId: accountPeerId, peer: peer, strings: strongSelf.presentationData.strings, nameDisplayOrder: strongSelf.presentationData.nameDisplayOrder), fixedPosition: nil, subject: .peer(peer))
```
- [ ] **Step 3: Grep to confirm zero remaining bridge sites**
Run:
```bash
grep -n "peerTokenTitle(.*_asPeer())" submodules/TelegramUI/Sources/ContactMultiselectionController.swift
```
Expected: **0 matches**.
If any match remains, the previous edits missed a line variant — re-read the file around each missed line and apply a targeted Edit for that variant.
- [ ] **Step 4: Confirm the 5 expected `peer: peer,` call sites now appear**
Run:
```bash
grep -n "peerTokenTitle(.*peer: peer," submodules/TelegramUI/Sources/ContactMultiselectionController.swift
```
Expected: 5 matches, line numbers approximately 171, 201, 386, 403, 748 (exact numbers unchanged — the edits don't shift line counts).
---
## Task 4: Build verification
**Files:** None edited in this task.
- [ ] **Step 1: Run the full project build with --continueOnError**
Run:
```bash
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 --configuration=debug_sim_arm64 \
--continueOnError
```
Expected: build succeeds with exit code 0 and no compilation errors.
**If the build fails:**
1. Inspect the error output. Three failure modes are anticipated (all should be rare given the scope):
- **Missing `displayTitle` on `EnginePeer`:** unlikely, since L27 was calling it pre-migration. If it happens, verify the `EnginePeer` import chain — but do not add new imports; this file already imports `TelegramCore`.
- **A 6th call site exists** that the pre-flight grep missed (e.g., one using a different string pattern like `peer:peer` with no space, or a multi-line call). Locate it with `grep -n "peerTokenTitle" submodules/TelegramUI/Sources/ContactMultiselectionController.swift` and apply the bridge drop manually.
- **Unrelated type-inference cascade**, e.g., some `peer` local was previously inferred as `Peer` via the callback chain and now can't be. Read the error line and assess: if it's inside the function body or call site, adjust; if it's elsewhere in the file, it was pre-existing and unrelated — still, don't touch it mid-wave. Abandon per wave-rule 5 if scope creep is required.
2. Re-run the build after the fix.
- [ ] **Step 2: Confirm the post-migration grep is clean**
Run (after successful build):
```bash
grep -n "peerTokenTitle(.*_asPeer())" submodules/TelegramUI/Sources/ContactMultiselectionController.swift
```
Expected: **0 matches**.
---
## Task 5: Commit
**Files:**
- `submodules/TelegramUI/Sources/ContactMultiselectionController.swift`
- [ ] **Step 1: Stage the one file**
Run:
```bash
git add submodules/TelegramUI/Sources/ContactMultiselectionController.swift
```
- [ ] **Step 2: Verify the staged diff**
Run:
```bash
git diff --cached --stat
```
Expected: `1 file changed, 6 insertions(+), 6 deletions(-)` (or thereabouts — 1 line's worth of signature change, 1 body-line change, 5 identical call-site changes; each is a 1-line replacement, net zero line-count delta).
Also run:
```bash
git diff --cached
```
Inspect manually to confirm: (a) the function signature changed `peer: Peer` → `peer: EnginePeer`; (b) the body `EnginePeer(peer).displayTitle(...)` → `peer.displayTitle(...)`; (c) 5 call sites lost `._asPeer()`. No other edits.
- [ ] **Step 3: Commit**
Run:
```bash
git commit -m "$(cat <<'EOF'
Postbox -> TelegramEngine wave 37
peerTokenTitle: peer parameter Peer -> EnginePeer.
Drops 5 _asPeer() bridges in ContactMultiselectionController.swift
(L171, L201, L386, L403, L748) - bridges installed by prior waves.
Private free function, single-file change.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 4: Confirm commit**
Run:
```bash
git log --oneline -3
```
Expected: the new wave-37 commit at the top.
---
## Task 6: Update memory / log
**Files:**
- Modify: `/Users/isaac/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/project_postbox_refactor_next_wave.md`
- Modify: `docs/superpowers/postbox-refactor-log.md`
- [ ] **Step 1: Read the current memory file for the refactor**
Read `/Users/isaac/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/project_postbox_refactor_next_wave.md`.
- [ ] **Step 2: Update frontmatter + add wave-37 entry**
Update the `description:` frontmatter field to reference wave 37 outcome (number of bridges dropped, build-iteration count, first-pass-clean-or-not). Add a bullet to "Latest commits" section with the new SHA and a one-line summary. Remove the "peerTokenTitle parameter migration" bullet from the "Wave 37 candidates" section (it's now landed). Update "Recommended wave 37" section to "Recommended wave 38" with a fresh recommendation from the remaining candidates.
- [ ] **Step 3: Read the refactor log**
Read `docs/superpowers/postbox-refactor-log.md`, locate the "Wave 36 outcome" section.
- [ ] **Step 4: Append wave-37 outcome**
Under the "Wave N outcomes" section, append a "Wave 37 outcome" subsection with:
- Commit SHA (from `git log --oneline -1`)
- File touched (1: ContactMultiselectionController.swift)
- Lines changed (6 deletions, 6 insertions)
- Bridges dropped (5)
- Build iterations to converge (should be 1)
- Any lessons observed (likely none — this wave is mechanical)
- [ ] **Step 5: Commit memory + log update**
Run:
```bash
git add docs/superpowers/postbox-refactor-log.md
git commit -m "$(cat <<'EOF'
docs: log wave 37 outcome
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
(Memory file under `~/.claude/` is not in the repo — save it separately via the Write tool; do not try to `git add` it.)
---
## Self-review results
**Spec coverage:** Every scope item in the spec maps to a task:
- Spec L21 signature change → Task 2 Step 2
- Spec L27 body simplification → Task 2 Step 2
- Spec L171/201/386/403/748 bridge drops → Task 3 Steps 1–2
- Spec verification (grep + build + post-grep) → Task 1 + Task 4
- Spec commit message → Task 5 Step 3
Out-of-scope items (L459, `import Postbox`, `accountPeerId: PeerId`) remain explicitly untouched — no task edits them.
**Placeholder scan:** No TBD, TODO, placeholder phrases, or "handle edge cases"-style hand-waves. Every step has a concrete command or code block.
**Type consistency:** `peer: EnginePeer`, `EnginePeer.Id` (= `PeerId` typealias), and `EnginePeer.displayTitle(strings:displayOrder:)` are all consistent across tasks.

666
docs/superpowers/plans/2026-04-24-rcp-peers-engine-migration.md
View file

@ -1,666 +0,0 @@
# Wave 44 — RenderedChannelParticipant.peers Engine-Peer Migration Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Migrate `RenderedChannelParticipant.peers: [PeerId: Peer]` to `[EnginePeer.Id: EnginePeer]`. Closes the wave-41 ratchet — the public struct no longer leaks raw Postbox `Peer` in any field.
**Architecture:** Single atomic commit. Declaration in TelegramCore changes; 8 TelegramCore producer functions wrap raw `Peer` values at their local-dict insertion points (inside transactions that already read from Postbox); 11 consumer-surface bridges drop (6 `EnginePeer(peer)` read-wraps + 5 `.mapValues({ $0._asPeer() })` constructor-unwrap transforms); 1 consumer-surface unwrap is added where an extracted `EnginePeer` value flows into a `SimpleDictionary<PeerId, Peer>`.
**Tech Stack:** Swift, Bazel (via `python3 build-system/Make/Make.py`), Postbox, TelegramCore, TelegramEngine. No unit tests — full-build verification only.
**Spec:** `docs/superpowers/specs/2026-04-24-rcp-peers-engine-migration-design.md`
---
## File Structure
All edits happen in existing files — no new files created. Touched files:
**TelegramCore (declaration + producers, 9 files):**
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelParticipants.swift` (declaration)
- `submodules/TelegramCore/Sources/TelegramEngine/Messages/RequestStartBot.swift`
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelOwnershipTransfer.swift`
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/JoinChannel.swift`
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/AddPeerMember.swift`
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/PeerAdmins.swift`
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelBlacklist.swift`
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/Ranks.swift`
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelMembers.swift`
**Consumers (drops + 1 add, 5 files):**
- `submodules/PeerInfoUI/Sources/ChannelAdminsController.swift`
- `submodules/PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift`
- `submodules/PeerInfoUI/Sources/ChannelMembersSearchControllerNode.swift`
- `submodules/PeerInfoUI/Sources/ChannelBlacklistController.swift`
- `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsHistoryTransition.swift`
**Total:** 14 files, ~30 edits, one atomic commit.
---
## Task 1: Pre-flight re-verification
**Purpose:** Confirm the grep surface matches the spec before editing anything. If any site count diverges, stop and update the spec.
**Files:** None modified.
- [ ] **Step 1.1: Verify 7 `participant.peers[...]` consumer read sites**
Run:
```bash
grep -rnE "participant\.peers\[|rcp\.peers\[|renderedParticipant\.peers\[" --include="*.swift" submodules/ 2>/dev/null
```
Expected output — exactly 6 bracketed-indexing sites (the 7th site, iteration without bracket-indexing, is checked in Step 1.2):
- `submodules/PeerInfoUI/Sources/ChannelAdminsController.swift:293`
- `submodules/PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift:835`
- `submodules/PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift:869`
- `submodules/PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift:1087`
- `submodules/PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift:1121`
- `submodules/PeerInfoUI/Sources/ChannelBlacklistController.swift:164`
If any line numbers differ by more than ±3 lines, re-read surrounding context to confirm identity. If a NEW site appears that isn't in the spec, STOP and update the spec before proceeding.
- [ ] **Step 1.2: Verify the iteration site is still at the expected line**
Run:
```bash
grep -nE "for \(.*,.* peer\) in participant\.peers" submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsHistoryTransition.swift
```
Expected: `672: for (_, peer) in participant.peers {`
- [ ] **Step 1.3: Verify all 8 TelegramCore producers still build `var peers: [PeerId: Peer] = [:]` locally**
Run:
```bash
grep -rnE "^[[:space:]]+var peers: \[PeerId: Peer\] = \[:\]" submodules/TelegramCore/Sources/TelegramEngine/ 2>/dev/null
```
Expected 8 matches, one per producer file:
- `Messages/RequestStartBot.swift:61`
- `Peers/ChannelOwnershipTransfer.swift:170`
- `Peers/JoinChannel.swift:59`
- `Peers/AddPeerMember.swift:242`
- `Peers/PeerAdmins.swift:251`
- `Peers/ChannelBlacklist.swift:128`
- `Peers/Ranks.swift:60`
- `Peers/ChannelMembers.swift:102`
If a producer is missing from this grep, check whether it now receives `peers` as a parameter rather than building locally — if so, STOP and update the spec (chain-migration needed).
- [ ] **Step 1.4: Verify no `as?` / `is TelegramX` casts exist on extracted dict values**
Run:
```bash
grep -rnE "peer = participant\.peers" --include="*.swift" -A 4 submodules/ 2>/dev/null | grep -E "as\?|is Telegram"
```
Expected output: empty. If this returns non-empty, STOP and update the spec.
- [ ] **Step 1.5: Verify no one is assigning into `participant.peers` (writes would break the migration)**
Run:
```bash
grep -rnE "participant\.peers\[[^]]+\][[:space:]]*=" --include="*.swift" submodules/ 2>/dev/null
```
Expected output: empty (`.peers` is a `let`; no writes possible anyway, but double-check).
---
## Task 2: Migrate declaration in ChannelParticipants.swift
**Purpose:** Change the struct field type and init default.
**Files:**
- Modify: `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelParticipants.swift:11, 14`
- [ ] **Step 2.1: Change field declaration**
In `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelParticipants.swift`, line 11:
```swift
// before
public let peers: [PeerId: Peer]
// after
public let peers: [EnginePeer.Id: EnginePeer]
```
- [ ] **Step 2.2: Change init default**
Same file, line 14:
```swift
// before
public init(participant: ChannelParticipant, peer: EnginePeer, peers: [PeerId: Peer] = [:], presences: [PeerId: PeerPresence] = [:]) {
// after
public init(participant: ChannelParticipant, peer: EnginePeer, peers: [EnginePeer.Id: EnginePeer] = [:], presences: [PeerId: PeerPresence] = [:]) {
```
Do NOT commit yet — this leaves the repo in a broken state until producers and consumers are updated.
---
## Task 3: Migrate TelegramCore producers (8 files)
**Purpose:** Each of the 8 TelegramCore producers builds a local `peers: [PeerId: Peer] = [:]` dict from raw Postbox peers inside a transaction. Migrate each local dict to `[EnginePeer.Id: EnginePeer] = [:]` and wrap every insertion value with `EnginePeer(...)`.
**Pattern (applies to every sub-step):**
```swift
// before
var peers: [PeerId: Peer] = [:]
peers[X.id] = X
// after
var peers: [EnginePeer.Id: EnginePeer] = [:]
peers[X.id] = EnginePeer(X)
```
The surrounding `presences: [PeerId: PeerPresence]` dict and the `RCP(..., peer: EnginePeer(X), ...)` wrap on the primary `peer` field both stay unchanged.
- [ ] **Step 3.1: Migrate `RequestStartBot.swift`**
File: `submodules/TelegramCore/Sources/TelegramEngine/Messages/RequestStartBot.swift`
Line 61: `var peers: [PeerId: Peer] = [:]` → `var peers: [EnginePeer.Id: EnginePeer] = [:]`
Line 64: `peers[peer.id] = peer` → `peers[peer.id] = EnginePeer(peer)`
- [ ] **Step 3.2: Migrate `ChannelOwnershipTransfer.swift`**
File: `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelOwnershipTransfer.swift`
Line 170: `var peers: [PeerId: Peer] = [:]` → `var peers: [EnginePeer.Id: EnginePeer] = [:]`
Line 172: `peers[accountUser.id] = accountUser` → `peers[accountUser.id] = EnginePeer(accountUser)`
Line 176: `peers[user.id] = user` → `peers[user.id] = EnginePeer(user)`
Line 180 is a double-RCP-construction; `peers:` reuses the same local — no change at line 180.
- [ ] **Step 3.3: Migrate `JoinChannel.swift`**
File: `submodules/TelegramCore/Sources/TelegramEngine/Peers/JoinChannel.swift`
Line 59: `var peers: [PeerId: Peer] = [:]` → `var peers: [EnginePeer.Id: EnginePeer] = [:]`
Line 64: `peers[account.peerId] = peer` → `peers[account.peerId] = EnginePeer(peer)`
Line 77: `peers[peer.id] = peer` → `peers[peer.id] = EnginePeer(peer)`
- [ ] **Step 3.4: Migrate `AddPeerMember.swift`**
File: `submodules/TelegramCore/Sources/TelegramEngine/Peers/AddPeerMember.swift`
Line 242: `var peers: [PeerId: Peer] = [:]` → `var peers: [EnginePeer.Id: EnginePeer] = [:]`
Line 244: `peers[memberPeer.id] = memberPeer` → `peers[memberPeer.id] = EnginePeer(memberPeer)`
Line 251: `peers[peer.id] = peer` → `peers[peer.id] = EnginePeer(peer)`
- [ ] **Step 3.5: Migrate `PeerAdmins.swift`**
File: `submodules/TelegramCore/Sources/TelegramEngine/Peers/PeerAdmins.swift`
Line 251: `var peers: [PeerId: Peer] = [:]` → `var peers: [EnginePeer.Id: EnginePeer] = [:]`
Line 253: `peers[adminPeer.id] = adminPeer` → `peers[adminPeer.id] = EnginePeer(adminPeer)`
Line 259: `peers[peer.id] = peer` → `peers[peer.id] = EnginePeer(peer)`
- [ ] **Step 3.6: Migrate `ChannelBlacklist.swift`**
File: `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelBlacklist.swift`
Line 128: `var peers: [PeerId: Peer] = [:]` → `var peers: [EnginePeer.Id: EnginePeer] = [:]`
Line 130: `peers[memberPeer.id] = memberPeer` → `peers[memberPeer.id] = EnginePeer(memberPeer)`
Line 136: `peers[peer.id] = peer` → `peers[peer.id] = EnginePeer(peer)`
- [ ] **Step 3.7: Migrate `Ranks.swift`**
File: `submodules/TelegramCore/Sources/TelegramEngine/Peers/Ranks.swift`
Line 60: `var peers: [PeerId: Peer] = [:]` → `var peers: [EnginePeer.Id: EnginePeer] = [:]`
Line 62: `peers[user.id] = user` → `peers[user.id] = EnginePeer(user)`
Line 68: `peers[peer.id] = peer` → `peers[peer.id] = EnginePeer(peer)`
- [ ] **Step 3.8: Migrate `ChannelMembers.swift`**
File: `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelMembers.swift`
Line 102: `var peers: [PeerId: Peer] = [:]` → `var peers: [EnginePeer.Id: EnginePeer] = [:]`
Line 105: `peers[peer.id] = peer` → `peers[peer.id] = EnginePeer(peer)`
- [ ] **Step 3.9: Post-producer verification**
Run:
```bash
grep -rnE "^[[:space:]]+var peers: \[PeerId: Peer\] = \[:\]" submodules/TelegramCore/Sources/TelegramEngine/ 2>/dev/null
```
Expected: no output (all 8 have been converted).
Run:
```bash
grep -rnE "^[[:space:]]+var peers: \[EnginePeer\.Id: EnginePeer\] = \[:\]" submodules/TelegramCore/Sources/TelegramEngine/ 2>/dev/null | wc -l
```
Expected: `8` (or ` 8`).
---
## Task 4: Drop 5 consumer `.mapValues({ $0._asPeer() })` transforms
**Purpose:** These consumer-side constructors build a `[EnginePeer.Id: EnginePeer]` source dict locally and currently unwrap to `[PeerId: Peer]` via `.mapValues({ $0._asPeer() })` to feed the old constructor signature. After Task 2, the constructor expects engine values directly — the transform becomes a no-op and is removed.
**Pattern (applies to every sub-step):**
```swift
// before
peers: peers.mapValues({ $0._asPeer() })
// after
peers: peers
```
- [ ] **Step 4.1: `ChannelAdminsController.swift:926`**
File: `submodules/PeerInfoUI/Sources/ChannelAdminsController.swift`
Line 926 (long line): locate the substring `peers: peers.mapValues({ $0._asPeer() })` and replace with `peers: peers`.
- [ ] **Step 4.2: `ChannelMembersSearchContainerNode.swift:994`**
File: `submodules/PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift`
Line 994: replace `peers: peers.mapValues({ $0._asPeer() })` → `peers: peers`.
- [ ] **Step 4.3: `ChannelMembersSearchContainerNode.swift:998`**
Same file, line 998: replace `peers: peers.mapValues({ $0._asPeer() })` → `peers: peers`.
- [ ] **Step 4.4: `ChannelMembersSearchControllerNode.swift:409`**
File: `submodules/PeerInfoUI/Sources/ChannelMembersSearchControllerNode.swift`
Line 409: replace `peers: peers.mapValues({ $0._asPeer() })` → `peers: peers`.
- [ ] **Step 4.5: `ChannelMembersSearchControllerNode.swift:413`**
Same file, line 413: replace `peers: peers.mapValues({ $0._asPeer() })` → `peers: peers`.
- [ ] **Step 4.6: Post-Task-4 verification**
Run:
```bash
grep -rnE "peers\.mapValues\(\{ \$0\._asPeer\(\) \}\)" --include="*.swift" submodules/ 2>/dev/null
```
Expected: no output (all 5 drops applied). If any remain, locate and drop.
---
## Task 5: Drop 6 consumer `EnginePeer(peer).displayTitle(...)` read-wraps
**Purpose:** Each site extracts `peer` from `participant.peers[X]`, wraps with `EnginePeer(peer)` to call `.displayTitle(...)`. After Task 2 the extracted `peer` is already `EnginePeer` — drop the wrap.
**Pattern (applies to every sub-step):**
```swift
// before
EnginePeer(peer).displayTitle(strings: ..., displayOrder: ...)
// after
peer.displayTitle(strings: ..., displayOrder: ...)
```
- [ ] **Step 5.1: `ChannelAdminsController.swift:297`**
File: `submodules/PeerInfoUI/Sources/ChannelAdminsController.swift`, line 297.
Replace:
```swift
peerText = strings.Channel_Management_PromotedBy(EnginePeer(peer).displayTitle(strings: strings, displayOrder: nameDisplayOrder)).string
```
with:
```swift
peerText = strings.Channel_Management_PromotedBy(peer.displayTitle(strings: strings, displayOrder: nameDisplayOrder)).string
```
The adjacent `peer.id == participant.peer.id` comparison at line 294 stays unchanged (both are `EnginePeer.Id`).
- [ ] **Step 5.2: `ChannelMembersSearchContainerNode.swift:839`**
File: `submodules/PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift`, line 839.
Replace:
```swift
label = presentationData.strings.Channel_Management_PromotedBy(EnginePeer(peer).displayTitle(strings: presentationData.strings, displayOrder: presentationData.nameDisplayOrder)).string
```
with:
```swift
label = presentationData.strings.Channel_Management_PromotedBy(peer.displayTitle(strings: presentationData.strings, displayOrder: presentationData.nameDisplayOrder)).string
```
- [ ] **Step 5.3: `ChannelMembersSearchContainerNode.swift:870`**
Same file, line 870.
Replace:
```swift
label = presentationData.strings.Channel_Management_RemovedBy(EnginePeer(peer).displayTitle(strings: presentationData.strings, displayOrder: presentationData.nameDisplayOrder)).string
```
with:
```swift
label = presentationData.strings.Channel_Management_RemovedBy(peer.displayTitle(strings: presentationData.strings, displayOrder: presentationData.nameDisplayOrder)).string
```
- [ ] **Step 5.4: `ChannelMembersSearchContainerNode.swift:1091`**
Same file, line 1091.
Replace:
```swift
label = presentationData.strings.Channel_Management_PromotedBy(EnginePeer(peer).displayTitle(strings: presentationData.strings, displayOrder: presentationData.nameDisplayOrder)).string
```
with:
```swift
label = presentationData.strings.Channel_Management_PromotedBy(peer.displayTitle(strings: presentationData.strings, displayOrder: presentationData.nameDisplayOrder)).string
```
- [ ] **Step 5.5: `ChannelMembersSearchContainerNode.swift:1122`**
Same file, line 1122.
Replace:
```swift
label = presentationData.strings.Channel_Management_RemovedBy(EnginePeer(peer).displayTitle(strings: presentationData.strings, displayOrder: presentationData.nameDisplayOrder)).string
```
with:
```swift
label = presentationData.strings.Channel_Management_RemovedBy(peer.displayTitle(strings: presentationData.strings, displayOrder: presentationData.nameDisplayOrder)).string
```
- [ ] **Step 5.6: `ChannelBlacklistController.swift:165`**
File: `submodules/PeerInfoUI/Sources/ChannelBlacklistController.swift`, line 165.
Replace:
```swift
text = .text(strings.Channel_Management_RemovedBy(EnginePeer(peer).displayTitle(strings: strings, displayOrder: nameDisplayOrder)).string, .secondary)
```
with:
```swift
text = .text(strings.Channel_Management_RemovedBy(peer.displayTitle(strings: strings, displayOrder: nameDisplayOrder)).string, .secondary)
```
- [ ] **Step 5.7: Post-Task-5 verification**
Run:
```bash
grep -rnE "EnginePeer\(peer\)\.displayTitle" --include="*.swift" submodules/PeerInfoUI/ 2>/dev/null
```
Expected: no output within PeerInfoUI. (Other modules may still have unrelated `EnginePeer(peer).displayTitle` usages on non-RCP-peers peers — those are out of scope.)
Run specifically for the 6 migrated sites:
```bash
grep -n "EnginePeer(peer)\.displayTitle" submodules/PeerInfoUI/Sources/ChannelAdminsController.swift submodules/PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift submodules/PeerInfoUI/Sources/ChannelBlacklistController.swift 2>/dev/null
```
Expected: no output.
---
## Task 6: Add 1 consumer unwrap at ChatRecentActionsHistoryTransition
**Purpose:** The one site that iterates `participant.peers` and inserts values into a `SimpleDictionary<PeerId, Peer>` container. After Task 2, the iterated `peer` is `EnginePeer`; the outer container still expects raw `Peer`. Unwrap at the insertion site.
**Files:**
- Modify: `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsHistoryTransition.swift:673`
- [ ] **Step 6.1: Replace insertion line**
In `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsHistoryTransition.swift`:
Context (lines 672–674, unchanged outside line 673):
```swift
for (_, peer) in participant.peers {
peers[peer.id] = peer
}
```
After edit:
```swift
for (_, peer) in participant.peers {
peers[peer.id] = peer._asPeer()
}
```
- [ ] **Step 6.2: Spot-check nearby wave-41 unwrap (reference, no change)**
Line 675 in the same function is `peers[participant.peer.id] = participant.peer._asPeer()` — a wave-41 artifact, unrelated to this wave. Leave unchanged.
---
## Task 7: Full build verification
**Purpose:** Verify the atomic change set compiles. Produces the ONLY real test signal for this wave.
**Files:** None modified; this is a build run.
- [ ] **Step 7.1: Run the full build**
Run:
```bash
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 --configuration=debug_sim_arm64 \
--continueOnError
```
Expected: build succeeds. Look for `INFO: Build completed successfully` near the end.
- [ ] **Step 7.2: If build fails — triage**
Expected failure patterns (from wave-41 lesson, budget 2–3 iterations):
1. **Missing producer wrap** — compiler error `cannot assign value of type 'Peer' to subscript of type 'EnginePeer'` (or similar) at a TelegramCore producer file → check that file's `var peers:` decl was converted AND all insertion RHS values are wrapped.
2. **Missed consumer site** — compiler error at a `.displayTitle` call on a raw Peer → find `EnginePeer(peer).displayTitle` site that Task 5 missed; drop the wrap.
3. **Mismatched mapValues drop** — `cannot convert value of type '[EnginePeer.Id: EnginePeer]' to expected argument type '[PeerId: Peer]'` → the spec's risk #3 triggered (a `.mapValues` site had a raw-Peer source after all); replace the drop with `peers.mapValues(EnginePeer.init)` at that site instead.
4. **New grep surface** — compiler complains about a site not in this plan → add it to the commit's scope; log it to the outcome doc.
Apply fixes, re-run Step 7.1. Repeat up to 3 iterations before re-evaluating scope.
- [ ] **Step 7.3: Post-build final grep audit**
Run:
```bash
grep -rnE "participant\.peers\[[^]]+\]" --include="*.swift" submodules/ 2>/dev/null
```
Expected: the same 6 read sites as Step 1.1 (now without `EnginePeer(peer)` wraps).
Run:
```bash
grep -rnE "peers\.mapValues\(\{ \$0\._asPeer\(\) \}\)" --include="*.swift" submodules/ 2>/dev/null
```
Expected: no output.
Run:
```bash
grep -n "public let peers: \[" submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelParticipants.swift
```
Expected: `11: public let peers: [EnginePeer.Id: EnginePeer]`.
---
## Task 8: Atomic commit
**Purpose:** Land all wave-44 edits in ONE commit. Explicitly enumerate files in `git add` (wave-39 lesson — re-confirmed in waves 41, 42, 43) to avoid pulling in the pre-existing working-tree WIP listed in the spec's risk section (`ListView.swift`, `ChatMessageTransitionNode.swift`, tulsi/, TgVoip/, libx264/).
**Files:** Commits all 14 wave-44 files.
- [ ] **Step 8.1: Confirm working-tree state**
Run:
```bash
git status --short
```
Expected (pre-existing WIP, unchanged):
- ` m build-system/bazel-rules/sourcekit-bazel-bsp`
- ` M submodules/Display/Source/ListView.swift` (do NOT include)
- ` M submodules/TelegramUI/Sources/ChatMessageTransitionNode.swift` (do NOT include)
- `?? build-system/tulsi/` (do NOT include)
- `?? submodules/TgVoip/` (do NOT include)
- `?? third-party/libx264/` (do NOT include)
Plus the wave-44 modified files:
- ` M submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelParticipants.swift`
- ` M submodules/TelegramCore/Sources/TelegramEngine/Messages/RequestStartBot.swift`
- ` M submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelOwnershipTransfer.swift`
- ` M submodules/TelegramCore/Sources/TelegramEngine/Peers/JoinChannel.swift`
- ` M submodules/TelegramCore/Sources/TelegramEngine/Peers/AddPeerMember.swift`
- ` M submodules/TelegramCore/Sources/TelegramEngine/Peers/PeerAdmins.swift`
- ` M submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelBlacklist.swift`
- ` M submodules/TelegramCore/Sources/TelegramEngine/Peers/Ranks.swift`
- ` M submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelMembers.swift`
- ` M submodules/PeerInfoUI/Sources/ChannelAdminsController.swift`
- ` M submodules/PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift`
- ` M submodules/PeerInfoUI/Sources/ChannelMembersSearchControllerNode.swift`
- ` M submodules/PeerInfoUI/Sources/ChannelBlacklistController.swift`
- ` M submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsHistoryTransition.swift`
If the set of wave-44-modified files doesn't match exactly (extra or missing), STOP and investigate before committing.
- [ ] **Step 8.2: Stage only wave-44 files**
Run:
```bash
git add \
submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelParticipants.swift \
submodules/TelegramCore/Sources/TelegramEngine/Messages/RequestStartBot.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelOwnershipTransfer.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/JoinChannel.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/AddPeerMember.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/PeerAdmins.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelBlacklist.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/Ranks.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelMembers.swift \
submodules/PeerInfoUI/Sources/ChannelAdminsController.swift \
submodules/PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift \
submodules/PeerInfoUI/Sources/ChannelMembersSearchControllerNode.swift \
submodules/PeerInfoUI/Sources/ChannelBlacklistController.swift \
submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsHistoryTransition.swift
```
- [ ] **Step 8.3: Verify staged set matches expected**
Run:
```bash
git diff --cached --stat
```
Expected: exactly 14 files staged, all from the wave-44 list. If `ListView.swift`, `ChatMessageTransitionNode.swift`, `bazel-rules/sourcekit-bazel-bsp`, `tulsi/`, `TgVoip/`, or `libx264/` appear here, unstage them.
- [ ] **Step 8.4: Commit**
Run:
```bash
git commit -m "$(cat <<'EOF'
Postbox -> TelegramEngine wave 44
Migrate RenderedChannelParticipant.peers from [PeerId: Peer] to
[EnginePeer.Id: EnginePeer]. Closes the wave-41 ratchet — the public
struct no longer leaks raw Peer types in any field (presences stays
Postbox-typed; separate migration).
Consumer-surface: -10 bridges. Dropped 6 EnginePeer(peer) read-wraps
at participant.peers[...] extraction sites across
ChannelAdminsController, ChannelMembersSearchContainerNode,
ChannelBlacklistController. Dropped 5 .mapValues({ $0._asPeer() })
constructor-unwrap transforms in ChannelAdminsController,
ChannelMembersSearchContainerNode, ChannelMembersSearchControllerNode.
Added 1 ._asPeer() at ChatRecentActionsHistoryTransition.swift:673
where the iterated value is inserted into a raw-Peer SimpleDictionary.
TelegramCore producers: 8 files build the local peers dict inside
postbox.transaction and wrap at the insertion point. ChannelMembers,
RequestStartBot, ChannelOwnershipTransfer, JoinChannel, AddPeerMember,
PeerAdmins, ChannelBlacklist, Ranks.
No unit tests in this project; full Telegram/Telegram build verified
under configuration=debug_sim_arm64.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 8.5: Verify commit**
Run:
```bash
git log -1 --stat
```
Expected: commit with 14 files changed, message starting with `Postbox -> TelegramEngine wave 44`.
Run:
```bash
git status --short
```
Expected: no M- or A-flagged wave-44 files (all committed); only the pre-existing WIP (`ListView.swift`, `ChatMessageTransitionNode.swift`, etc.) remains.
---
## Rollback
If the wave cannot be completed (e.g., build fails after 4+ iterations and the scope balloons beyond plan):
```bash
git restore --staged \
submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelParticipants.swift \
submodules/TelegramCore/Sources/TelegramEngine/Messages/RequestStartBot.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelOwnershipTransfer.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/JoinChannel.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/AddPeerMember.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/PeerAdmins.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelBlacklist.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/Ranks.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelMembers.swift \
submodules/PeerInfoUI/Sources/ChannelAdminsController.swift \
submodules/PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift \
submodules/PeerInfoUI/Sources/ChannelMembersSearchControllerNode.swift \
submodules/PeerInfoUI/Sources/ChannelBlacklistController.swift \
submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsHistoryTransition.swift
git checkout -- \
submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelParticipants.swift \
submodules/TelegramCore/Sources/TelegramEngine/Messages/RequestStartBot.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelOwnershipTransfer.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/JoinChannel.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/AddPeerMember.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/PeerAdmins.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelBlacklist.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/Ranks.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelMembers.swift \
submodules/PeerInfoUI/Sources/ChannelAdminsController.swift \
submodules/PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift \
submodules/PeerInfoUI/Sources/ChannelMembersSearchControllerNode.swift \
submodules/PeerInfoUI/Sources/ChannelBlacklistController.swift \
submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsHistoryTransition.swift
```
Then document what was learned in an outcome doc and update `project_postbox_refactor_next_wave.md`.
---
## Success criteria (from spec)
1. ✅ `ChannelParticipants.swift` has `peers: [EnginePeer.Id: EnginePeer]` declaration (Task 2).
2. ✅ All 8 TelegramCore producers compile with wrapped inserts (Task 3).
3. ✅ All 5 consumer `.mapValues({ $0._asPeer() })` transforms are removed (Task 4).
4. ✅ All 6 consumer `EnginePeer(peer).displayTitle(...)` wraps on extracted dict values are removed (Task 5).
5. ✅ `ChatRecentActionsHistoryTransition.swift:673` uses `peer._asPeer()` for the SimpleDictionary insertion value (Task 6).
6. ✅ Full `Telegram/Telegram` build (`configuration=debug_sim_arm64`) is clean — **one** atomic commit (Tasks 7, 8).
7. ✅ Grep post-migration: `participant.peers[` returns only engine-typed call sites; no residual `EnginePeer(peer)` on `.peers[...]` extractions (Steps 5.7, 7.3).

860
docs/superpowers/plans/2026-04-24-renderedchannelparticipant-peer-engine-peer-migration.md
View file

@ -1,860 +0,0 @@
# Wave 41 — `RenderedChannelParticipant.peer → EnginePeer` Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Migrate `TelegramCore.RenderedChannelParticipant.peer` from Postbox `Peer` to TelegramCore `EnginePeer`. Drop ~37 bridges (net ~−14 after adds) and eliminate 2 Shape-C ratchet wraps installed by wave 39.
**Architecture:** Single atomic commit. One TelegramCore struct field change + 16 TelegramCore internal construction sites wrapped with `EnginePeer(peer)` + 17 consumer files updated: ZERO sites untouched (~160), ~32 DROP sites unwrapped, 9 CAST sites rewritten to pattern-match, 3 ADD-ASPEER sites append `._asPeer()`, 7 ADD-WRAP consumer constructors wrap raw `Peer` with `EnginePeer`.
**Tech Stack:** Swift, Bazel (`Make.py` wrapper), TelegramCore, Postbox → TelegramEngine refactor conventions per `CLAUDE.md`.
**Build command:**
```sh
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 --configuration=debug_sim_arm64 --continueOnError
```
---
## File Structure
**Created:** none.
**Modified (27 files):**
TelegramCore (10 files):
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelParticipants.swift` — struct field type + init param + Equatable impl
- `submodules/TelegramCore/Sources/TelegramEngine/Messages/RequestStartBot.swift` — 1 constructor wrap
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/AddPeerMember.swift` — 1 constructor wrap
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelAdminEventLogs.swift` — 7 constructor wraps
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelBlacklist.swift` — 1 constructor wrap
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelMembers.swift` — 1 constructor wrap
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelOwnershipTransfer.swift` — 2 constructor wraps
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/JoinChannel.swift` — 1 constructor wrap
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/PeerAdmins.swift` — 1 constructor wrap
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/Ranks.swift` — 1 constructor wrap
PeerInfoUI (6 files):
- `submodules/PeerInfoUI/Sources/ChannelAdminsController.swift`
- `submodules/PeerInfoUI/Sources/ChannelBlacklistController.swift`
- `submodules/PeerInfoUI/Sources/ChannelMembersController.swift`
- `submodules/PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift`
- `submodules/PeerInfoUI/Sources/ChannelMembersSearchControllerNode.swift`
- `submodules/PeerInfoUI/Sources/ChannelPermissionsController.swift`
Other consumers (11 files):
- `submodules/SearchPeerMembers/Sources/SearchPeerMembers.swift`
- `submodules/TelegramUI/Components/AdminUserActionsSheet/Sources/AdminUserActionsSheet.swift`
- `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsController.swift`
- `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsFilterController.swift`
- `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsHistoryTransition.swift`
- `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoMembers.swift`
- `submodules/TelegramUI/Components/ShareWithPeersScreen/Sources/ShareWithPeersScreenState.swift`
- `submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryContentLiveChatComponent.swift`
- `submodules/TelegramUI/Sources/ChatControllerAdminBanUsers.swift`
- `submodules/TemporaryCachedPeerDataManager/Sources/ChannelMemberCategoryListContext.swift` *(no `participant.peer` edits needed — all ZERO; file touched only if build surfaces type issues)*
- `submodules/TemporaryCachedPeerDataManager/Sources/PeerChannelMemberCategoriesContextsManager.swift` *(no edits expected — only `item.peer.id` reference is ZERO)*
---
## Task 1: Migrate the struct definition
**File:** `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelParticipants.swift`
- [ ] **Step 1.1: Edit struct field, init param, and Equatable impl**
Replace the entire struct body:
```swift
public struct RenderedChannelParticipant: Equatable {
public let participant: ChannelParticipant
public let peer: EnginePeer
public let peers: [PeerId: Peer]
public let presences: [PeerId: PeerPresence]
public init(participant: ChannelParticipant, peer: EnginePeer, peers: [PeerId: Peer] = [:], presences: [PeerId: PeerPresence] = [:]) {
self.participant = participant
self.peer = peer
self.peers = peers
self.presences = presences
}
public static func ==(lhs: RenderedChannelParticipant, rhs: RenderedChannelParticipant) -> Bool {
return lhs.participant == rhs.participant && lhs.peer == rhs.peer
}
}
```
Note: the file already imports both `Postbox` (for `Peer`/`PeerId`/`PeerPresence`) and TelegramCore internal symbols (`EnginePeer` visible from within the same module). No import changes needed.
---
## Task 2: Wrap TelegramCore-internal constructor sites
Each site receives a raw `Peer` and must now wrap it with `EnginePeer(peer)`. All edits are identical in shape.
- [ ] **Step 2.1:** `submodules/TelegramCore/Sources/TelegramEngine/Messages/RequestStartBot.swift:65`
Before:
```swift
return .channelParticipant(RenderedChannelParticipant(participant: participant, peer: peer, peers: peers, presences: presences))
```
After:
```swift
return .channelParticipant(RenderedChannelParticipant(participant: participant, peer: EnginePeer(peer), peers: peers, presences: presences))
```
- [ ] **Step 2.2:** `submodules/TelegramCore/Sources/TelegramEngine/Peers/AddPeerMember.swift:255`
Before:
```swift
return (currentParticipant, RenderedChannelParticipant(participant: updatedParticipant, peer: memberPeer, peers: peers, presences: presences))
```
After:
```swift
return (currentParticipant, RenderedChannelParticipant(participant: updatedParticipant, peer: EnginePeer(memberPeer), peers: peers, presences: presences))
```
- [ ] **Step 2.3:** `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelAdminEventLogs.swift` — 7 constructor wraps
Line 271:
```swift
action = .participantInvite(RenderedChannelParticipant(participant: participant, peer: peer))
// becomes:
action = .participantInvite(RenderedChannelParticipant(participant: participant, peer: EnginePeer(peer)))
```
Line 279 (two constructors on one line):
```swift
action = .participantToggleBan(prev: RenderedChannelParticipant(participant: prevParticipant, peer: prevPeer), new: RenderedChannelParticipant(participant: newParticipant, peer: newPeer))
// becomes:
action = .participantToggleBan(prev: RenderedChannelParticipant(participant: prevParticipant, peer: EnginePeer(prevPeer)), new: RenderedChannelParticipant(participant: newParticipant, peer: EnginePeer(newPeer)))
```
Line 287 (two constructors on one line):
```swift
action = .participantToggleAdmin(prev: RenderedChannelParticipant(participant: prevParticipant, peer: prevPeer), new: RenderedChannelParticipant(participant: newParticipant, peer: newPeer))
// becomes:
action = .participantToggleAdmin(prev: RenderedChannelParticipant(participant: prevParticipant, peer: EnginePeer(prevPeer)), new: RenderedChannelParticipant(participant: newParticipant, peer: EnginePeer(newPeer)))
```
Line 483 (two constructors on one line):
```swift
action = .participantSubscriptionExtended(prev: RenderedChannelParticipant(participant: prevParticipant, peer: prevPeer), new: RenderedChannelParticipant(participant: newParticipant, peer: newPeer))
// becomes:
action = .participantSubscriptionExtended(prev: RenderedChannelParticipant(participant: prevParticipant, peer: EnginePeer(prevPeer)), new: RenderedChannelParticipant(participant: newParticipant, peer: EnginePeer(newPeer)))
```
- [ ] **Step 2.4:** `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelBlacklist.swift:140`
Before:
```swift
return (currentParticipant, RenderedChannelParticipant(participant: updatedParticipant, peer: memberPeer, peers: peers, presences: presences), isMember)
```
After:
```swift
return (currentParticipant, RenderedChannelParticipant(participant: updatedParticipant, peer: EnginePeer(memberPeer), peers: peers, presences: presences), isMember)
```
- [ ] **Step 2.5:** `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelMembers.swift:115`
Before:
```swift
items.append(RenderedChannelParticipant(participant: participant, peer: peer, peers: peers, presences: renderedPresences))
```
After:
```swift
items.append(RenderedChannelParticipant(participant: participant, peer: EnginePeer(peer), peers: peers, presences: renderedPresences))
```
- [ ] **Step 2.6:** `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelOwnershipTransfer.swift:180`
Before:
```swift
return [(currentCreator, RenderedChannelParticipant(participant: updatedPreviousCreator, peer: accountUser, peers: peers, presences: presences)), (currentParticipant, RenderedChannelParticipant(participant: updatedParticipant, peer: user, peers: peers, presences: presences))]
```
After:
```swift
return [(currentCreator, RenderedChannelParticipant(participant: updatedPreviousCreator, peer: EnginePeer(accountUser), peers: peers, presences: presences)), (currentParticipant, RenderedChannelParticipant(participant: updatedParticipant, peer: EnginePeer(user), peers: peers, presences: presences))]
```
- [ ] **Step 2.7:** `submodules/TelegramCore/Sources/TelegramEngine/Peers/JoinChannel.swift:82`
Before:
```swift
return RenderedChannelParticipant(participant: updatedParticipant, peer: peer, peers: peers, presences: presences)
```
After:
```swift
return RenderedChannelParticipant(participant: updatedParticipant, peer: EnginePeer(peer), peers: peers, presences: presences)
```
- [ ] **Step 2.8:** `submodules/TelegramCore/Sources/TelegramEngine/Peers/PeerAdmins.swift:262`
Before:
```swift
return (currentParticipant, RenderedChannelParticipant(participant: updatedParticipant, peer: adminPeer, peers: peers, presences: presences))
```
After:
```swift
return (currentParticipant, RenderedChannelParticipant(participant: updatedParticipant, peer: EnginePeer(adminPeer), peers: peers, presences: presences))
```
- [ ] **Step 2.9:** `submodules/TelegramCore/Sources/TelegramEngine/Peers/Ranks.swift:95`
Before:
```swift
return (currentParticipant, RenderedChannelParticipant(participant: updatedParticipant, peer: user, peers: peers, presences: presences))
```
After:
```swift
return (currentParticipant, RenderedChannelParticipant(participant: updatedParticipant, peer: EnginePeer(user), peers: peers, presences: presences))
```
---
## Task 3: Consumer — PeerInfoUI/ChannelAdminsController.swift
**File:** `submodules/PeerInfoUI/Sources/ChannelAdminsController.swift`
- [ ] **Step 3.1:** Line 326 — DROP `EnginePeer(participant.peer)` wrap.
Before:
```swift
return ItemListPeerItem(presentationData: presentationData, systemStyle: .glass, dateTimeFormat: dateTimeFormat, nameDisplayOrder: nameDisplayOrder, context: arguments.context, peer: EnginePeer(participant.peer), presence: participant.presences[participant.peer.id].flatMap { EnginePeer.Presence($0) }, text: peerText.isEmpty ? .presence : .text(peerText, .secondary), label: label, editing: editing, revealOptions: revealOptions, switchValue: nil, enabled: enabled, selectable: true, sectionId: self.section, action: action, setPeerIdWithRevealedOptions: { previousId, id in
```
After: replace `peer: EnginePeer(participant.peer)` → `peer: participant.peer` (leave the rest of the line intact).
- [ ] **Step 3.2:** Line 921 — DROP `._asPeer()` in constructor.
Before:
```swift
result.append(RenderedChannelParticipant(participant: .creator(id: peer.id, adminInfo: nil, rank: rank), peer: peer._asPeer(), presences: presences))
```
After:
```swift
result.append(RenderedChannelParticipant(participant: .creator(id: peer.id, adminInfo: nil, rank: rank), peer: peer, presences: presences))
```
(`peer` here is already `EnginePeer` — confirmed by surrounding code where `creatorPeer: EnginePeer?` is assigned from this same loop variable.)
- [ ] **Step 3.3:** Line 926 — DROP `._asPeer()` in constructor.
Before:
```swift
result.append(RenderedChannelParticipant(participant: .member(id: peer.id, invitedAt: 0, adminInfo: ChannelParticipantAdminInfo(rights: TelegramChatAdminRights(rights: .internal_groupSpecific), promotedBy: creator.id, canBeEditedByAccountPeer: creator.id == context.account.peerId), banInfo: nil, rank: rank, subscriptionUntilDate: nil), peer: peer._asPeer(), peers: peers.mapValues({ $0._asPeer() }), presences: presences))
```
After: change `peer: peer._asPeer()` → `peer: peer`. Leave `peers.mapValues({ $0._asPeer() })` intact — `peers` field is unchanged.
---
## Task 4: Consumer — PeerInfoUI/ChannelBlacklistController.swift
**File:** `submodules/PeerInfoUI/Sources/ChannelBlacklistController.swift`
- [ ] **Step 4.1:** Line 170 (or 381 — the site installed by wave 39; the file has one site `EnginePeer(participant.peer)`)
Before:
```swift
peer: EnginePeer(participant.peer)
```
After:
```swift
peer: participant.peer
```
Note: the file may have a single such site; use:
```
grep -n 'EnginePeer(participant\.peer)' submodules/PeerInfoUI/Sources/ChannelBlacklistController.swift
```
and DROP every match.
---
## Task 5: Consumer — PeerInfoUI/ChannelMembersController.swift
**File:** `submodules/PeerInfoUI/Sources/ChannelMembersController.swift`
- [ ] **Step 5.1:** Line 305 — CAST rewrite.
Before:
```swift
if let user = participant.peer as? TelegramUser, let _ = user.botInfo {
```
After:
```swift
if case let .user(user) = participant.peer, let _ = user.botInfo {
```
- [ ] **Step 5.2:** Line 334 — DROP wrap.
Before:
```swift
peer: EnginePeer(participant.peer)
```
After:
```swift
peer: participant.peer
```
- [ ] **Step 5.3:** Line 707 — DROP wrap (the wave-39-installed Shape-C wrap).
Before:
```swift
peer: EnginePeer(participant.peer)
```
After:
```swift
peer: participant.peer
```
---
## Task 6: Consumer — PeerInfoUI/ChannelMembersSearchContainerNode.swift
**File:** `submodules/PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift`
This file has the most sites (4 CAST, 3 DROP pairs, 3 ADD-WRAP constructor sites).
- [ ] **Step 6.1:** Line 212 — DROP two wraps on one line.
Before:
```swift
peer: .peer(peer: EnginePeer(participant.peer), chatPeer: EnginePeer(participant.peer)),
```
After:
```swift
peer: .peer(peer: participant.peer, chatPeer: participant.peer),
```
- [ ] **Step 6.2:** Line 223 — DROP wrap.
Before:
```swift
interaction.peerSelected(EnginePeer(participant.peer), participant)
```
After:
```swift
interaction.peerSelected(participant.peer, participant)
```
- [ ] **Step 6.3:** Line 752 — CAST rewrite.
Before:
```swift
if excludeBots, let user = participant.peer as? TelegramUser, user.botInfo != nil {
```
After:
```swift
if excludeBots, case let .user(user) = participant.peer, user.botInfo != nil {
```
- [ ] **Step 6.4:** Line 884 — CAST rewrite. Same pattern as 6.3.
- [ ] **Step 6.5:** Line 987 — ADD-WRAP constructor.
Before:
```swift
renderedParticipant = RenderedChannelParticipant(participant: .creator(id: peer.id, adminInfo: nil, rank: nil), peer: peer)
```
After:
```swift
renderedParticipant = RenderedChannelParticipant(participant: .creator(id: peer.id, adminInfo: nil, rank: nil), peer: EnginePeer(peer))
```
(`peer` here is raw `Peer` from `peerView.peers[participant.peerId]` — confirmed by surrounding iteration code.)
- [ ] **Step 6.6:** Line 994 — ADD-WRAP constructor.
Change `peer: peer` to `peer: EnginePeer(peer)`. Full site for reference:
```swift
renderedParticipant = RenderedChannelParticipant(participant: .member(id: peer.id, invitedAt: 0, adminInfo: ChannelParticipantAdminInfo(rights: TelegramChatAdminRights(rights: TelegramChatAdminRightsFlags.peerSpecific(peer: .legacyGroup(group))), promotedBy: creatorPeer?.id ?? context.account.peerId, canBeEditedByAccountPeer: creatorPeer?.id == context.account.peerId), banInfo: nil, rank: nil, subscriptionUntilDate: nil), peer: peer, peers: peers.mapValues({ $0._asPeer() }))
```
Change only `peer: peer,` → `peer: EnginePeer(peer),`.
- [ ] **Step 6.7:** Line 998 — ADD-WRAP constructor.
```swift
renderedParticipant = RenderedChannelParticipant(participant: .member(id: peer.id, invitedAt: 0, adminInfo: nil, banInfo: nil, rank: nil, subscriptionUntilDate: nil), peer: peer, peers: peers.mapValues({ $0._asPeer() }))
```
Change only `peer: peer,` → `peer: EnginePeer(peer),`.
- [ ] **Step 6.8:** Line 1052 — CAST rewrite. Same pattern as 6.3.
- [ ] **Step 6.9:** Line 1136 — CAST rewrite. Same pattern as 6.3.
---
## Task 7: Consumer — PeerInfoUI/ChannelMembersSearchControllerNode.swift
**File:** `submodules/PeerInfoUI/Sources/ChannelMembersSearchControllerNode.swift`
- [ ] **Step 7.1:** Line 148 — DROP wrap.
Before:
```swift
peer: EnginePeer(participant.peer)
```
After:
```swift
peer: participant.peer
```
(The line has the wrap appearing twice — search the file for `EnginePeer(participant.peer)` and drop each occurrence. Use Edit with `replace_all` if unambiguous.)
- [ ] **Step 7.2:** Line 404 — ADD-WRAP constructor.
Before:
```swift
renderedParticipant = RenderedChannelParticipant(participant: .creator(id: peer.id, adminInfo: nil, rank: nil), peer: peer, presences: peerView.peerPresences)
```
After:
```swift
renderedParticipant = RenderedChannelParticipant(participant: .creator(id: peer.id, adminInfo: nil, rank: nil), peer: EnginePeer(peer), presences: peerView.peerPresences)
```
- [ ] **Step 7.3:** Line 409 — ADD-WRAP constructor.
Change `peer: peer,` → `peer: EnginePeer(peer),` in the full line:
```swift
renderedParticipant = RenderedChannelParticipant(participant: .member(id: peer.id, invitedAt: 0, adminInfo: ChannelParticipantAdminInfo(rights: TelegramChatAdminRights(rights: TelegramChatAdminRightsFlags.peerSpecific(peer: EnginePeer(mainPeer))), promotedBy: creator.id, canBeEditedByAccountPeer: creator.id == context.account.peerId), banInfo: nil, rank: nil, subscriptionUntilDate: nil), peer: peer, peers: peers.mapValues({ $0._asPeer() }), presences: peerView.peerPresences)
```
- [ ] **Step 7.4:** Line 413 — ADD-WRAP constructor. Same `peer: peer,` → `peer: EnginePeer(peer),`.
- [ ] **Step 7.5:** Line 516 — CAST rewrite.
Before:
```swift
if let user = participant.peer as? TelegramUser, user.botInfo != nil {
```
After:
```swift
if case let .user(user) = participant.peer, user.botInfo != nil {
```
- [ ] **Step 7.6:** Line 558 — CAST rewrite. Same pattern as 7.5.
---
## Task 8: Consumer — PeerInfoUI/ChannelPermissionsController.swift
**File:** `submodules/PeerInfoUI/Sources/ChannelPermissionsController.swift`
- [ ] **Step 8.1:** Lines 480 and 483 — DROP wraps.
Both lines contain `EnginePeer(participant.peer)`. Change each to `participant.peer`.
If the two occurrences are unambiguous, use Edit with `replace_all=true` on `EnginePeer(participant.peer)` → `participant.peer`.
---
## Task 9: Consumer — SearchPeerMembers/SearchPeerMembers.swift
**File:** `submodules/SearchPeerMembers/Sources/SearchPeerMembers.swift`
- [ ] **Step 9.1:** Lines 30, 36, 61, 76 — DROP wraps.
All four sites are `EnginePeer(participant.peer)`. Use Edit with `replace_all=true`:
- old: `EnginePeer(participant.peer)`
- new: `participant.peer`
Verify with `grep -n 'EnginePeer(participant\.peer)' submodules/SearchPeerMembers/Sources/SearchPeerMembers.swift` → should return empty after edit.
---
## Task 10: Consumer — ChatRecentActionsController.swift
**File:** `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsController.swift`
- [ ] **Step 10.1:** Line 359 — DROP wrap.
Before:
```swift
EnginePeer(participant.peer)
```
After:
```swift
participant.peer
```
---
## Task 11: Consumer — ChatRecentActionsFilterController.swift
**File:** `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsFilterController.swift`
- [ ] **Step 11.1:** Line 217 — DROP wrap.
Change `EnginePeer(participant.peer)` → `participant.peer` on line 217.
- [ ] **Step 11.2:** Line 445 — ADD-WRAP constructor rewrite.
Before:
```swift
if let peer = peer, case let .user(user) = peer {
return RenderedChannelParticipant(participant: .member(id: user.id, invitedAt: 0, adminInfo: nil, banInfo: nil, rank: nil, subscriptionUntilDate: nil), peer: user)
}
```
After:
```swift
if let peer = peer, case let .user(user) = peer {
return RenderedChannelParticipant(participant: .member(id: user.id, invitedAt: 0, adminInfo: nil, banInfo: nil, rank: nil, subscriptionUntilDate: nil), peer: .user(user))
}
```
(`.user(user)` is the enum case `EnginePeer.user(TelegramUser)`. Alternative: `peer: EnginePeer(user)` or `peer: peer` — but `peer: peer` reuses the already-unwrapped EnginePeer and is the cleanest. Use `peer: peer`.)
Preferred after:
```swift
if let peer = peer, case let .user(user) = peer {
return RenderedChannelParticipant(participant: .member(id: user.id, invitedAt: 0, adminInfo: nil, banInfo: nil, rank: nil, subscriptionUntilDate: nil), peer: peer)
}
```
---
## Task 12: Consumer — ChatRecentActionsHistoryTransition.swift
**File:** `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsHistoryTransition.swift`
This is the highest-volume consumer file (12 `EnginePeer(new.peer)` sites + 2 ADD-ASPEER sites).
- [ ] **Step 12.1:** DROP all `EnginePeer(new.peer)` wraps.
Use Edit with `replace_all=true`:
- old: `EnginePeer(new.peer)`
- new: `new.peer`
After: grep `EnginePeer(new\.peer)` should return empty.
- [ ] **Step 12.2:** Line 675 — ADD-ASPEER.
Before:
```swift
peers[participant.peer.id] = participant.peer
```
After:
```swift
peers[participant.peer.id] = participant.peer._asPeer()
```
(Target dict is `SimpleDictionary<PeerId, Peer>`; the value side needs raw Peer.)
- [ ] **Step 12.3:** Line 2275 — ADD-ASPEER.
Before:
```swift
peers[new.peer.id] = new.peer
```
After:
```swift
peers[new.peer.id] = new.peer._asPeer()
```
---
## Task 13: Consumer — PeerInfoMembers.swift
**File:** `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoMembers.swift`
- [ ] **Step 13.1:** Line 33 — ADD-ASPEER.
Before:
```swift
var peer: Peer {
switch self {
case let .channelMember(participant, _):
return participant.peer
```
After:
```swift
var peer: Peer {
switch self {
case let .channelMember(participant, _):
return participant.peer._asPeer()
```
No other edits in this file. The `participant.peer.id` accesses at lines 22, 44 are ZERO; `item.peer.id` at line 171 is ZERO.
---
## Task 14: Consumer — ShareWithPeersScreenState.swift
**File:** `submodules/TelegramUI/Components/ShareWithPeersScreen/Sources/ShareWithPeersScreenState.swift`
- [ ] **Step 14.1:** Line 558 — DROP wrap.
Before:
```swift
peers.append(EnginePeer(participant.peer))
```
After:
```swift
peers.append(participant.peer)
```
- [ ] **Step 14.2:** Line 566 — CAST rewrite.
Before:
```swift
if let user = participant.peer as? TelegramUser, user.botInfo != nil {
```
After:
```swift
if case let .user(user) = participant.peer, user.botInfo != nil {
```
- [ ] **Step 14.3:** Line 576 — DROP wrap.
Before:
```swift
peers.append(EnginePeer(participant.peer))
```
After:
```swift
peers.append(participant.peer)
```
---
## Task 15: Consumer — AdminUserActionsSheet.swift
**File:** `submodules/TelegramUI/Components/AdminUserActionsSheet/Sources/AdminUserActionsSheet.swift`
This file has ~6 `EnginePeer(peer.peer)` / `EnginePeer(component.peers[0].peer)` wraps and many ZERO sites.
- [ ] **Step 15.1:** Use Edit with `replace_all=true`:
- old: `EnginePeer(peer.peer)`
- new: `peer.peer`
This covers lines 284, 522, 523.
- [ ] **Step 15.2:** Edit the `EnginePeer(component.peers[0].peer)` sites at lines 404, 416, 417.
Use Edit with `replace_all=true`:
- old: `EnginePeer(component.peers[0].peer)`
- new: `component.peers[0].peer`
- [ ] **Step 15.3:** Verify no other `EnginePeer(` wraps around `.peer` accesses remain on `RenderedChannelParticipant`. Run:
```
grep -n 'EnginePeer(.*\.peer)' submodules/TelegramUI/Components/AdminUserActionsSheet/Sources/AdminUserActionsSheet.swift
```
Confirm remaining matches are on non-RCP types (e.g., some other context-derived peer).
---
## Task 16: Consumer — StoryContentLiveChatComponent.swift
**File:** `submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryContentLiveChatComponent.swift`
- [ ] **Step 16.1:** Line 370 — DROP `._asPeer()` in constructor.
Before:
```swift
peer: author._asPeer()
```
After:
```swift
peer: author
```
(`author` is `EnginePeer` — confirmed by the surrounding code that uses `author.id` and by the `chatPeer` signal's return type.)
---
## Task 17: Consumer — ChatControllerAdminBanUsers.swift
**File:** `submodules/TelegramUI/Sources/ChatControllerAdminBanUsers.swift`
- [ ] **Step 17.1:** Line 226 — ADD-WRAP constructor.
Before:
```swift
let peer = author
renderedParticipants.append(RenderedChannelParticipant(
participant: participant,
peer: peer
))
```
After:
```swift
let peer = author
renderedParticipants.append(RenderedChannelParticipant(
participant: participant,
peer: EnginePeer(peer)
))
```
(Confirmed `author` is raw `Peer` via `presentMultiBanMessageOptions(... authors: [Peer], ...)` signature on line 45.)
- [ ] **Step 17.2:** Line 372 — DROP `._asPeer()` in constructor.
Before:
```swift
peer: authorPeer._asPeer()
```
After:
```swift
peer: authorPeer
```
(Confirmed `authorPeer` is `EnginePeer?` at line 327 via `engine.data.get(Peer.Peer(id:))` signal; already guard-unwrapped.)
- [ ] **Step 17.3:** Line 757 — DROP `._asPeer()` in constructor.
Same edit pattern as 17.2: `peer: authorPeer._asPeer()` → `peer: authorPeer`.
---
## Task 18: Full build verification
- [ ] **Step 18.1:** Run the full build with `--continueOnError`.
```sh
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 --configuration=debug_sim_arm64 --continueOnError
```
Expected: build success. First-pass-clean is the goal (wave-39 pattern applies — classification is exact, migration is mechanical, no inference-bearing return types).
If the build fails, expect errors only in files in this plan. Any error outside the plan's file list is either:
- a pre-existing unrelated WIP (e.g., `ChatMessageTransitionNode.swift`) — not a wave-41 issue
- a genuine miss in pre-flight classification — record which file, update the plan, and re-run
For each error in wave-41 files:
1. Read the error
2. Classify: is it a shape we mis-identified (ZERO that's not actually transparent) or a new shape (dict subscript, function arg to a `Peer`-typed param, etc.)?
3. Apply the appropriate fix (`._asPeer()` if raw Peer needed; unwrap the wrap if EnginePeer needed)
4. Re-run the build
Budget: 1–3 build iterations.
- [ ] **Step 18.2:** Post-build grep verification.
Run these greps and confirm they return only the expected residual matches:
```sh
grep -rn 'EnginePeer(participant\.peer)' submodules/ --include='*.swift' | grep -v submodules/TelegramCore/ | grep -v submodules/Postbox/
```
Expected: empty.
```sh
grep -rn 'EnginePeer(new\.peer)' submodules/ --include='*.swift' | grep -v submodules/TelegramCore/
```
Expected: empty.
```sh
grep -rn 'participant\.peer as\? TelegramUser' submodules/ --include='*.swift'
```
Expected: empty.
```sh
grep -n 'public let peer:' submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelParticipants.swift
```
Expected: `public let peer: EnginePeer`.
---
## Task 19: Commit
- [ ] **Step 19.1:** Stage only wave-41 files (explicitly enumerate — wave-39 lesson).
```sh
git status --short
```
Inspect the output. Only wave-41 files should appear as modified. If pre-existing WIP (e.g., `submodules/TelegramUI/Sources/ChatMessageTransitionNode.swift`) is also modified, do NOT include it in the commit.
```sh
git add \
submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelParticipants.swift \
submodules/TelegramCore/Sources/TelegramEngine/Messages/RequestStartBot.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/AddPeerMember.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelAdminEventLogs.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelBlacklist.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelMembers.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelOwnershipTransfer.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/JoinChannel.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/PeerAdmins.swift \
submodules/TelegramCore/Sources/TelegramEngine/Peers/Ranks.swift \
submodules/PeerInfoUI/Sources/ChannelAdminsController.swift \
submodules/PeerInfoUI/Sources/ChannelBlacklistController.swift \
submodules/PeerInfoUI/Sources/ChannelMembersController.swift \
submodules/PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift \
submodules/PeerInfoUI/Sources/ChannelMembersSearchControllerNode.swift \
submodules/PeerInfoUI/Sources/ChannelPermissionsController.swift \
submodules/SearchPeerMembers/Sources/SearchPeerMembers.swift \
submodules/TelegramUI/Components/AdminUserActionsSheet/Sources/AdminUserActionsSheet.swift \
submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsController.swift \
submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsFilterController.swift \
submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsHistoryTransition.swift \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoMembers.swift \
submodules/TelegramUI/Components/ShareWithPeersScreen/Sources/ShareWithPeersScreenState.swift \
submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryContentLiveChatComponent.swift \
submodules/TelegramUI/Sources/ChatControllerAdminBanUsers.swift \
docs/superpowers/specs/2026-04-24-renderedchannelparticipant-peer-engine-peer-migration-design.md \
docs/superpowers/plans/2026-04-24-renderedchannelparticipant-peer-engine-peer-migration.md
```
(Add any additional files the build iterations surfaced.)
Run `git status --short` and confirm only staged wave-41 files are green, and any unrelated WIP is still marked as unstaged.
- [ ] **Step 19.2:** Commit.
```sh
git commit -m "$(cat <<'EOF'
Postbox -> TelegramEngine wave 41
Migrate RenderedChannelParticipant.peer from Postbox `Peer` to
TelegramCore `EnginePeer`. 27 files touched: 10 TelegramCore
(1 struct + 9 files with constructor wraps) + 17 consumer files.
Drops the 2 Shape-C wraps installed by wave 39 (ChannelMembersController
and ChannelBlacklistController) plus ~37 additional EnginePeer(...) /
._asPeer() bridges across the consumer surface. Net ~-14 bridges
after the 16 TelegramCore-internal EnginePeer(peer) wraps and the 7
consumer ADD-WRAP constructor sites. RCP.peers and RCP.presences
dictionaries remain Postbox-typed (deferred).
EOF
)"
```
- [ ] **Step 19.3:** Confirm commit landed and working tree is clean except for pre-existing WIP.
```sh
git status --short
git log -1 --oneline
```
---
## Task 20: Log the wave outcome
- [ ] **Step 20.1:** Append wave 41 entry to `docs/superpowers/postbox-refactor-log.md`.
Format (matching prior wave entries):
```markdown
## Wave 41 outcome — RenderedChannelParticipant.peer: Peer → EnginePeer (2026-04-24)
Landed as commit `<hash>`. 27 files / ~45 site edits / net ~-14 bridges.
**Shape distribution:**
- TelegramCore: 16 constructor sites wrapped with `EnginePeer(peer)` across 9 files + struct field migrated in ChannelParticipants.swift
- Consumers: ~32 DROP (EnginePeer/._asPeer unwraps), 9 CAST (as? TelegramUser → if case let .user), 3 ADD-ASPEER, 7 ADD-WRAP constructor sites
**First-pass-clean:** <yes|no, iterations count>. Extends wave-39 lesson: first-pass-clean
is achievable when classification is exact and all patterns are mechanical.
**Ratchet economics:** drops 2 wave-39 Shape-C wraps
(ChannelMembersController:707, ChannelBlacklistController:381) and installs 7 ADD-WRAP
consumer constructor sites as ratchet markers for a future
`RenderedChannelParticipant.peers: [PeerId: Peer] → [EnginePeer.Id: EnginePeer]` wave.
**Spec:** `docs/superpowers/specs/2026-04-24-renderedchannelparticipant-peer-engine-peer-migration-design.md`.
**Plan:** `docs/superpowers/plans/2026-04-24-renderedchannelparticipant-peer-engine-peer-migration.md`.
```
- [ ] **Step 20.2:** Update the `project_postbox_refactor_next_wave.md` memory file with the wave 41 outcome and the wave 42 candidate (likely `PeerInfoScreenData.peer → EnginePeer`).
- [ ] **Step 20.3:** Commit docs updates.
```sh
git add docs/superpowers/postbox-refactor-log.md
git commit -m "$(cat <<'EOF'
docs: log wave 41 outcome
EOF
)"
```

666
docs/superpowers/plans/2026-04-24-sendaspeer-engine-peer-migration.md
View file

@ -1,666 +0,0 @@
# Wave 35: `SendAsPeer.peer: Peer → EnginePeer` Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Migrate the public field `SendAsPeer.peer` from the Postbox `Peer` protocol to the TelegramCore `EnginePeer` enum in a single atomic commit. Drops 3 `._asPeer()` bridges at construction sites, collapses 6 redundant `EnginePeer(peer.peer)` wraps, rewrites 1 `peer.peer as? TelegramChannel` downcast to an enum pattern, and adds `EnginePeer(channel)` wraps at 2 raw-`TelegramChannel` construction sites. No outflow `._asPeer()` bridges need to be added for this wave (unlike wave 34's `ContactListPeer.peer(peer:)` bridge).
**Architecture:** One atomic commit. The field-type change is necessarily atomic (half-migrated SendAsPeer doesn't compile), so all edits land together. TelegramCore's `_internal_*SendAsAvailablePeers` functions keep `import Postbox` — only `SendAsPeer`'s public surface changes. No new wrappers, no new typealiases. The manual `==` body is replaced with synthesized Equatable (EnginePeer is Equatable).
**Tech Stack:** Swift, Bazel build via Make.py wrapper. No tests — verification is build success + targeted grep checks.
**Spec:** `docs/superpowers/specs/2026-04-24-sendaspeer-engine-peer-migration-design.md`
---
## File Structure
**Modified files (7 expected — 1 TelegramCore + 6 consumer. Plus 2 "verify no-edit" files.)**
| File | Edit count | Category |
|---|---|---|
| `submodules/TelegramCore/Sources/TelegramEngine/Messages/SendAsPeers.swift` | ~7 spot edits (struct change + 4 constructor wraps + drop manual `==`) | α |
| `submodules/TelegramUI/Components/Chat/ChatSendAsContextMenu/Sources/ChatSendAsPeerListContextItem.swift` | ~5 (1 cast rewrite + 4 wrap drops) | γ |
| `submodules/TelegramUI/Sources/Chat/ChatControllerLoadDisplayNode.swift` | 3 (1 bridge-drop + 2 EnginePeer wraps on raw channel) | δ |
| `submodules/TelegramUI/Components/Chat/ChatTextInputPanelNode/Sources/ChatTextInputPanelComponent.swift` | 1 (bridge-drop) | δ |
| `submodules/TelegramUI/Components/Chat/ChatTextInputPanelNode/Sources/ChatTextInputPanelNode.swift` | 1 (wrap collapse) | δ |
| `submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerViewSendMessage.swift` | ~4 (1 bridge-drop + 1 flatMap simplify + 1 map simplify) | δ |
**Verify-only (no edits expected):**
| File | Reason |
|---|---|
| `submodules/ChatPresentationInterfaceState/Sources/ChatPresentationInterfaceState.swift` | Holds `[SendAsPeer]?` at collection level, no `.peer` access. |
| `submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerComponent.swift` | Passes `currentSendAsPeer` through to `ChatSendAsPeerListContextItem` which keeps taking `[SendAsPeer]`. |
**EnginePeer enum case mapping (used in cast rewrite):**
| Postbox concrete | EnginePeer case |
|---|---|
| `TelegramChannel` | `.channel(TelegramChannel)` |
| `TelegramGroup` | `.legacyGroup(TelegramGroup)` |
| `TelegramUser` | `.user(TelegramUser)` |
---
## Task 1: Edit `SendAsPeers.swift` — struct definition + constructor wraps
**Files:**
- Modify: `submodules/TelegramCore/Sources/TelegramEngine/Messages/SendAsPeers.swift`
Foundational change. Without it, none of the consumer edits compile.
- [ ] **Step 1.1: Update the SendAsPeer struct field, init parameter, and drop manual `==`**
Edit:
```swift
// OLD
public struct SendAsPeer: Equatable {
public let peer: Peer
public let subscribers: Int32?
public let isPremiumRequired: Bool
public init(peer: Peer, subscribers: Int32?, isPremiumRequired: Bool) {
self.peer = peer
self.subscribers = subscribers
self.isPremiumRequired = isPremiumRequired
}
public static func ==(lhs: SendAsPeer, rhs: SendAsPeer) -> Bool {
return lhs.peer.isEqual(rhs.peer) && lhs.subscribers == rhs.subscribers && lhs.isPremiumRequired == rhs.isPremiumRequired
}
}
```
```swift
// NEW
public struct SendAsPeer: Equatable {
public let peer: EnginePeer
public let subscribers: Int32?
public let isPremiumRequired: Bool
public init(peer: EnginePeer, subscribers: Int32?, isPremiumRequired: Bool) {
self.peer = peer
self.subscribers = subscribers
self.isPremiumRequired = isPremiumRequired
}
}
```
Use the Edit tool with the OLD block as `old_string` and the NEW block as `new_string`. Swift synthesizes Equatable for structs where every stored property is Equatable: `EnginePeer` is Equatable, `Int32?` is Equatable, `Bool` is Equatable — so the manual `==` is no longer needed.
- [ ] **Step 1.2: Wrap raw Postbox `Peer` values at the four constructor sites**
Sites at lines 64, 170, 236, 330. Each binds a raw Postbox `Peer` (from `transaction.getPeer(peerId)` or `peers.map { ... }`) and passes it to the `SendAsPeer(peer: ...)` init. Wrap each with `EnginePeer(...)`.
Edit (line 64, inside `_internal_cachedPeerSendAsAvailablePeers`, cache-hit branch):
```swift
// OLD
peers.append(SendAsPeer(peer: peer, subscribers: subscribers, isPremiumRequired: cached.premiumRequiredPeerIds.contains(peer.id)))
```
```swift
// NEW
peers.append(SendAsPeer(peer: EnginePeer(peer), subscribers: subscribers, isPremiumRequired: cached.premiumRequiredPeerIds.contains(peer.id)))
```
Edit (line 170, inside `_internal_peerSendAsAvailablePeers`, network-response map):
```swift
// OLD
return peers.map { SendAsPeer(peer: $0, subscribers: subscribers[$0.id], isPremiumRequired: premiumRequiredPeerIds.contains($0.id)) }
```
```swift
// NEW
return peers.map { SendAsPeer(peer: EnginePeer($0), subscribers: subscribers[$0.id], isPremiumRequired: premiumRequiredPeerIds.contains($0.id)) }
```
Edit (line 236, inside `_internal_cachedLiveStorySendAsAvailablePeers`, cache-hit branch):
```swift
// OLD
peers.append(SendAsPeer(peer: peer, subscribers: subscribers, isPremiumRequired: cached.premiumRequiredPeerIds.contains(peer.id)))
```
```swift
// NEW
peers.append(SendAsPeer(peer: EnginePeer(peer), subscribers: subscribers, isPremiumRequired: cached.premiumRequiredPeerIds.contains(peer.id)))
```
Note: lines 64 and 236 have identical text. If you prefer `replace_all=true`, do a grep first to confirm the count is exactly 2, then apply once.
Edit (line 330, inside `_internal_liveStorySendAsAvailablePeers`, network-response map):
```swift
// OLD
return peers.map { SendAsPeer(peer: $0, subscribers: subscribers[$0.id], isPremiumRequired: premiumRequiredPeerIds.contains($0.id)) }
```
```swift
// NEW
return peers.map { SendAsPeer(peer: EnginePeer($0), subscribers: subscribers[$0.id], isPremiumRequired: premiumRequiredPeerIds.contains($0.id)) }
```
Same remark as above: lines 170 and 330 are identical — one `replace_all=true` covers both if the count is exactly 2.
- [ ] **Step 1.3: Verify** — read the updated file and confirm:
- The struct's `peer` field is now `EnginePeer`
- The init parameter is `peer: EnginePeer`
- Manual `==` has been removed
- All 4 constructor sites wrap with `EnginePeer(...)`
- `peer.peer.id` accesses inside the caching loops (lines 87, 90, 259, 262) remain unchanged (`EnginePeer.id` typealias to `PeerId` keeps them valid)
Do not commit yet.
---
## Task 2: Edit `ChatSendAsPeerListContextItem.swift` — cast rewrite + wrap collapse
**Files:**
- Modify: `submodules/TelegramUI/Components/Chat/ChatSendAsContextMenu/Sources/ChatSendAsPeerListContextItem.swift`
1 Postbox-concrete downcast rewrite + 4 `EnginePeer(peer.peer)` wrap drops.
- [ ] **Step 2.1: Rewrite the `peer.peer as? TelegramChannel` downcast at line 73**
Edit:
```swift
// OLD
} else if let subscribers = peer.subscribers {
if let peer = peer.peer as? TelegramChannel {
if case .broadcast = peer.info {
```
```swift
// NEW
} else if let subscribers = peer.subscribers {
if case let .channel(channel) = peer.peer {
if case .broadcast = channel.info {
```
Note: the original `if let peer = peer.peer as? TelegramChannel` shadows the outer `peer: SendAsPeer` loop variable. The rewrite uses `channel` to avoid shadowing. Any subsequent uses of `peer.info`, `peer.flags`, etc. inside the inner `if let peer = ...` block must be renamed to `channel.*`.
Read lines 70–90 before editing to see the full extent of the shadowed-`peer` scope, and ensure every reference to `peer.info` (and any sibling field access like `peer.flags`, `peer.username`, etc.) within the inner block is rewritten to `channel.*`. The snippet above captures the only `peer.info` site from the inventory.
- [ ] **Step 2.2: Drop `EnginePeer(peer.peer)` wraps at lines 89, 110, 116, 121**
The field `peer.peer` is now `EnginePeer`, so `EnginePeer(peer.peer)` becomes a type error. Drop the wrap.
Read the full lines first to confirm each site's shape. Expected patterns (edit one at a time with enough surrounding context to make each unique — the four sites likely differ in surrounding tokens):
For each of the four sites, the pattern to eliminate is `EnginePeer(peer.peer)` → `peer.peer`. Example:
```swift
// OLD
let title = EnginePeer(peer.peer).displayTitle(strings: strings, displayOrder: nameDisplayOrder)
```
```swift
// NEW
let title = peer.peer.displayTitle(strings: strings, displayOrder: nameDisplayOrder)
```
Identify each of the four sites (lines 89, 110, 116, 121) by reading the file, then apply one Edit per site using enough surrounding context (usually 1–2 tokens before/after the `EnginePeer(peer.peer)` subexpression) to make the `old_string` unique.
If all four lines reduce to the same substring pattern (e.g., `EnginePeer(peer.peer)` as a standalone subexpression), `replace_all=true` on the substring `EnginePeer(peer.peer)` → `peer.peer` is safe — but **first** grep to confirm the count is exactly 4 and no other meaning is captured.
Run before: `grep -cE "EnginePeer\(peer\.peer\)" submodules/TelegramUI/Components/Chat/ChatSendAsContextMenu/Sources/ChatSendAsPeerListContextItem.swift`
Expected: 4.
- [ ] **Step 2.3: Verify** — grep:
Run: `grep -nE "peer\.peer\s+(as\?|is)\s+Telegram|EnginePeer\(peer\.peer\)" submodules/TelegramUI/Components/Chat/ChatSendAsContextMenu/Sources/ChatSendAsPeerListContextItem.swift`
Expected: zero matches.
---
## Task 3: Edit `ChatControllerLoadDisplayNode.swift` — bridge-drop + raw-channel wraps
**Files:**
- Modify: `submodules/TelegramUI/Sources/Chat/ChatControllerLoadDisplayNode.swift`
1 `._asPeer()` bridge-drop at line 772 + 2 `EnginePeer(channel)` wraps for raw `TelegramChannel` at lines 805 and 823.
- [ ] **Step 3.1: Bridge-drop at line 772**
Edit:
```swift
// OLD
return SendAsPeer(peer: peer._asPeer(), subscribers: nil, isPremiumRequired: false)
```
```swift
// NEW
return SendAsPeer(peer: peer, subscribers: nil, isPremiumRequired: false)
```
Verification: the surrounding signal chain binds `peer` as `EnginePeer` (from `context.engine.data.get(TelegramEngine.EngineData.Item.Peer.Peer(id: ...))`). The `._asPeer()` bridge is no longer needed.
If the line text differs from the OLD block above (e.g., different field order or trailing arguments), read the file around line 772 and adjust the `old_string` to match byte-for-byte before editing.
- [ ] **Step 3.2: Wrap raw `TelegramChannel` at line 805**
Read lines 800–812 to see the bound `channel` variable. The construction site should be `SendAsPeer(peer: channel, ...)` where `channel: TelegramChannel` is raw Postbox.
Edit:
```swift
// OLD
SendAsPeer(peer: channel, subscribers: subscribers, isPremiumRequired: isPremiumRequired)
```
```swift
// NEW
SendAsPeer(peer: EnginePeer(channel), subscribers: subscribers, isPremiumRequired: isPremiumRequired)
```
If the surrounding context differs (different field values), match the actual line text when writing `old_string`.
- [ ] **Step 3.3: Wrap raw `TelegramChannel` at line 823**
Same pattern as Step 3.2. Read lines 818–830 first, identify the `SendAsPeer(peer: channel, ...)` construction site, and wrap `channel` with `EnginePeer(...)`.
If the line text at 805 and 823 is identical, `replace_all=true` on the substring `SendAsPeer(peer: channel,` → `SendAsPeer(peer: EnginePeer(channel),` covers both. **First** grep to confirm the count:
Run before: `grep -cE "SendAsPeer\(peer: channel," submodules/TelegramUI/Sources/Chat/ChatControllerLoadDisplayNode.swift`
Expected: 2.
- [ ] **Step 3.4: Verify** — grep:
Run: `grep -nE "SendAsPeer\(peer:\s+\w+\._asPeer\(\)|SendAsPeer\(peer:\s+channel," submodules/TelegramUI/Sources/Chat/ChatControllerLoadDisplayNode.swift`
Expected: zero matches. Lines 792, 826, 835, 844 retaining `.peer.id` accesses are expected and correct.
---
## Task 4: Edit `ChatTextInputPanelComponent.swift` — bridge-drop
**Files:**
- Modify: `submodules/TelegramUI/Components/Chat/ChatTextInputPanelNode/Sources/ChatTextInputPanelComponent.swift`
1 `._asPeer()` bridge-drop.
- [ ] **Step 4.1: Bridge-drop at line 847**
Read lines 843–853 to confirm the surrounding signal chain and the type of `sendAsConfiguration.currentPeer` (expected: `EnginePeer`).
Edit:
```swift
// OLD
let sendAsPeers = [SendAsPeer(peer: sendAsConfiguration.currentPeer._asPeer(), subscribers: nil, isPremiumRequired: false)]
```
```swift
// NEW
let sendAsPeers = [SendAsPeer(peer: sendAsConfiguration.currentPeer, subscribers: nil, isPremiumRequired: false)]
```
If the actual line text wraps across multiple lines or uses different field values, match the real text byte-for-byte when writing `old_string`.
- [ ] **Step 4.2: Verify** — grep:
Run: `grep -nE "SendAsPeer\(peer:.*\._asPeer\(\)" submodules/TelegramUI/Components/Chat/ChatTextInputPanelNode/Sources/ChatTextInputPanelComponent.swift`
Expected: zero matches.
---
## Task 5: Edit `ChatTextInputPanelNode.swift` — wrap collapse
**Files:**
- Modify: `submodules/TelegramUI/Components/Chat/ChatTextInputPanelNode/Sources/ChatTextInputPanelNode.swift`
1 `EnginePeer(peer)` wrap collapse at line 1625.
- [ ] **Step 5.1: Collapse `EnginePeer(peer)` wrap**
Read lines 1615–1630 to see the full context. `peer` is bound from a preceding `var currentPeer = sendAsPeers.first(where: { $0.peer.id == ... })?.peer` (lines 1620–1622). After migration, `.peer` returns `EnginePeer`, so `EnginePeer(peer)` on an `EnginePeer` is a type error.
Exact edit depends on the actual line text. Example shape:
```swift
// OLD (at or near line 1625)
let enginePeer = EnginePeer(peer)
```
```swift
// NEW
let enginePeer = peer
```
Read lines 1623–1628 first and write the Edit with byte-accurate `old_string`. If the bound variable is then used as `enginePeer.displayTitle(...)`, consider whether the rename can be eliminated entirely (e.g., rename `peer` uses downstream), but prefer the minimal edit for commit clarity.
Lines 1616, 1620, 1622, 2948, 5370 should remain unchanged — they perform `.peer.id` comparisons or `.first(where:)` lookups that work identically on `[SendAsPeer]` with `EnginePeer`-typed `.peer`.
- [ ] **Step 5.2: Verify** — grep:
Run: `grep -nE "EnginePeer\(peer\)" submodules/TelegramUI/Components/Chat/ChatTextInputPanelNode/Sources/ChatTextInputPanelNode.swift`
Expected: zero matches. If any remain, inspect each — they may be unrelated wraps on non-SendAsPeer-sourced `peer` variables (in which case they must stay).
---
## Task 6: Edit `StoryItemSetContainerViewSendMessage.swift` — multi-site cleanup
**Files:**
- Modify: `submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerViewSendMessage.swift`
1 bridge-drop + 1 flatMap simplify + 1 map simplify. Many other `.peer.id` / `.peer` accesses remain unchanged.
- [ ] **Step 6.1: Bridge-drop at line 249**
Read lines 244–254 to confirm `accountPeer` is typed as `EnginePeer` upstream.
Edit:
```swift
// OLD
availablePeers.append(SendAsPeer(
peer: accountPeer._asPeer(),
subscribers: nil,
isPremiumRequired: false
))
```
```swift
// NEW
availablePeers.append(SendAsPeer(
peer: accountPeer,
subscribers: nil,
isPremiumRequired: false
))
```
If the actual layout (whitespace, line breaks) differs from the OLD block, match the real text byte-for-byte when writing `old_string`.
- [ ] **Step 6.2: Simplify flatMap at line 4080**
`EnginePeer.init` as a function reference expects a raw `Peer` and returns `EnginePeer`. After migration, `sendAsPeer?.peer` is already `EnginePeer?`, so `.flatMap(EnginePeer.init)` is both unnecessary and a type error.
Edit:
```swift
// OLD
myPeer: (sendAsPeer?.peer).flatMap(EnginePeer.init),
```
```swift
// NEW
myPeer: sendAsPeer?.peer,
```
Read lines 4078–4082 first to confirm the surrounding labeled-argument layout and match byte-for-byte.
- [ ] **Step 6.3: Simplify map at line 4081**
`.map({ EnginePeer($0.peer) })` wraps each already-`EnginePeer` value in `EnginePeer(...)` — a type error. Drop the wrap.
Edit:
```swift
// OLD
availableSendAsPeers: component.isEmbeddedInCamera ? [] : (self.sendAsData?.availablePeers.map({ EnginePeer($0.peer) }) ?? []),
```
```swift
// NEW
availableSendAsPeers: component.isEmbeddedInCamera ? [] : (self.sendAsData?.availablePeers.map({ $0.peer }) ?? []),
```
Read lines 4079–4083 first to confirm the exact line text.
- [ ] **Step 6.4: Verify** — grep:
Run: `grep -nE "SendAsPeer\(peer:.*\._asPeer\(\)|EnginePeer\(\$0\.peer\)|\(sendAsPeer\?\.peer\)\.flatMap\(EnginePeer\.init\)" submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerViewSendMessage.swift`
Expected: zero matches.
Retained-as-is accesses (inventory-verified correct after migration): `.peer.id` at lines 254, 688, 4088, 4089, 4327, 4333, 4340, 4356, 4372; optional chaining at 4050, 4068, 4069. These should NOT be edited.
---
## Task 7: Verify "no-edit" consumer files
**Files:**
- Read: `submodules/ChatPresentationInterfaceState/Sources/ChatPresentationInterfaceState.swift`
- Read: `submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerComponent.swift`
Sanity-check: confirm neither file contains `.peer as?`/`is`, `EnginePeer(.peer)`, or `._asPeer()` patterns tied to SendAsPeer. If any such pattern is found, fold the fix into the relevant task above before the build pass.
- [ ] **Step 7.1: Grep ChatPresentationInterfaceState.swift**
Run: `grep -nE "SendAsPeer|sendAsPeers" submodules/ChatPresentationInterfaceState/Sources/ChatPresentationInterfaceState.swift`
Expected shape: field declaration, init param, assignment, equality comparison, `updatedSendAsPeers(_:)` method — all at the `[SendAsPeer]?` collection level. No `.peer` field access.
- [ ] **Step 7.2: Grep StoryItemSetContainerComponent.swift**
Run: `grep -nE "SendAsPeer|currentSendAsPeer|\.peer\b" submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerComponent.swift | grep -iE "sendAsPeer|\.peer"`
Read lines 3056–3072 to confirm `sendMessageContext.currentSendAsPeer` is only passed through to `ChatSendAsPeerListContextItem` (which keeps `[SendAsPeer]`) or accessed for `.peer.id` comparisons — neither requires an edit.
If the verification shows an edit is needed, add the edit as an additional step under the relevant Task 2–6. Do not edit here silently.
---
## Task 8: Build verification (first pass)
- [ ] **Step 8.1: Run the full build with `--continueOnError`**
Run:
```bash
source ~/.zshrc 2>/dev/null && python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 --configuration=debug_sim_arm64 --continueOnError 2>&1 | tee /tmp/wave35-build.log
```
Expected outcome: ideally clean. Realistic outcome: 0–5 errors at sites the inventory missed.
- [ ] **Step 8.2: Triage build errors**
Likely error patterns and their fixes:
| Error | Fix |
|---|---|
| `cannot convert value of type 'EnginePeer' to expected argument type 'Peer'` at site passing `peer.peer` | Add `._asPeer()` bridge: `peer.peer._asPeer()` |
| `cannot convert value of type 'Peer' to expected argument type 'EnginePeer'` at `SendAsPeer(peer: ...)` | Add wrap: `SendAsPeer(peer: EnginePeer(<raw>), ...)` |
| `value of type 'EnginePeer' has no member 'isEqual'` | Replace with `==` |
| `pattern of type 'TelegramChannel' cannot match values of type 'EnginePeer'` | Missed C2 — rewrite to `if case .channel(let channel) = peer.peer` form |
| `cannot invoke initializer for type 'EnginePeer' with an argument list of type '(EnginePeer)'` | Missed wrap collapse — drop `EnginePeer(...)` |
| `extraneous argument label 'peer:' in call` or similar on `SendAsPeer(...)` | Check that the construction arg is `EnginePeer`, not raw — add `EnginePeer(...)` wrap |
For each error, identify the file:line, apply the appropriate fix, and re-run the build until clean.
- [ ] **Step 8.3: Iterate to clean build**
Re-run the build after each batch of fixes. The wave is complete when the build returns 0 errors for the targeted configuration.
If 10+ unexpected errors surface, halt and reassess: the inventory was significantly incomplete and the wave may need to be split into pre-cleanup commits. Discuss with user before continuing.
---
## Task 9: Post-build grep validations
- [ ] **Step 9.1: Bridge-drop validation**
Run:
```bash
grep -rn "SendAsPeer(peer:.*\._asPeer()" submodules/ --include="*.swift" | grep -v "^submodules/TelegramCore/" | grep -v "^submodules/Postbox/"
```
Expected: zero hits. If any remain, those are missed bridge-drops — fix and re-run Task 8.
- [ ] **Step 9.2: Wrap-collapse validation**
Run:
```bash
for f in submodules/TelegramUI/Components/Chat/ChatSendAsContextMenu/Sources/ChatSendAsPeerListContextItem.swift \
submodules/TelegramUI/Sources/Chat/ChatControllerLoadDisplayNode.swift \
submodules/TelegramUI/Components/Chat/ChatTextInputPanelNode/Sources/ChatTextInputPanelComponent.swift \
submodules/TelegramUI/Components/Chat/ChatTextInputPanelNode/Sources/ChatTextInputPanelNode.swift \
submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerViewSendMessage.swift; do
echo "=== $f ==="
grep -nE "EnginePeer\(peer\.peer\)|EnginePeer\(\$0\.peer\)|\(sendAsPeer\?\.peer\)\.flatMap\(EnginePeer\.init\)" "$f"
done
```
Expected: zero hits across all 5 files.
- [ ] **Step 9.3: C2 cast validation**
Run:
```bash
grep -nE "peer\.peer\s+(as\?|is)\s+Telegram" submodules/TelegramUI/Components/Chat/ChatSendAsContextMenu/Sources/ChatSendAsPeerListContextItem.swift
```
Expected: zero hits.
- [ ] **Step 9.4: Construction-site validation**
Ensure all `SendAsPeer(peer: ...)` construction sites outside TelegramCore provide `EnginePeer`:
```bash
grep -rnE "SendAsPeer\(peer:" submodules/ --include="*.swift" | grep -v "^submodules/TelegramCore/"
```
Inspect each hit. Expected forms: `SendAsPeer(peer: <engine-peer-expr>, ...)` or `SendAsPeer(peer: EnginePeer(<raw>), ...)`. Anything of the form `SendAsPeer(peer: <raw-Peer>, ...)` is a miss — fix.
If any of the validations fail, return to Task 8 to fix.
---
## Task 10: Atomic commit + memory + log update
- [ ] **Step 10.1: Stage and review**
Run:
```bash
git status --short
git diff --stat
```
Confirm exactly 6 modified Swift files (1 TelegramCore + 5 consumer — or 7 if Task 7 surfaced a needed edit). Files expected:
- `submodules/TelegramCore/Sources/TelegramEngine/Messages/SendAsPeers.swift`
- `submodules/TelegramUI/Components/Chat/ChatSendAsContextMenu/Sources/ChatSendAsPeerListContextItem.swift`
- `submodules/TelegramUI/Sources/Chat/ChatControllerLoadDisplayNode.swift`
- `submodules/TelegramUI/Components/Chat/ChatTextInputPanelNode/Sources/ChatTextInputPanelComponent.swift`
- `submodules/TelegramUI/Components/Chat/ChatTextInputPanelNode/Sources/ChatTextInputPanelNode.swift`
- `submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerViewSendMessage.swift`
WIP from earlier (`build-system/bazel-rules/sourcekit-bazel-bsp`, `ChatListFilterPresetController.swift`, `ChatListFilterPresetListController.swift`, untracked `build-system/tulsi/` / `submodules/TgVoip/` / `third-party/libx264/`) should NOT be staged.
The `docs/superpowers/plans/2026-04-22-claude-md-reorganization.md` untracked file should ALSO remain unstaged.
- [ ] **Step 10.2: Stage only the wave-35 files**
Run:
```bash
git add submodules/TelegramCore/Sources/TelegramEngine/Messages/SendAsPeers.swift \
submodules/TelegramUI/Components/Chat/ChatSendAsContextMenu/Sources/ChatSendAsPeerListContextItem.swift \
submodules/TelegramUI/Sources/Chat/ChatControllerLoadDisplayNode.swift \
submodules/TelegramUI/Components/Chat/ChatTextInputPanelNode/Sources/ChatTextInputPanelComponent.swift \
submodules/TelegramUI/Components/Chat/ChatTextInputPanelNode/Sources/ChatTextInputPanelNode.swift \
submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerViewSendMessage.swift
```
If Task 7 surfaced an additional file, append it here.
- [ ] **Step 10.3: Commit**
Run:
```bash
git commit -m "$(cat <<'EOF'
Postbox -> TelegramEngine wave 35: SendAsPeer.peer Peer -> EnginePeer
Migrates the public field `SendAsPeer.peer` from the Postbox `Peer`
protocol to the TelegramCore `EnginePeer` enum. Internal
`_internal_*SendAsAvailablePeers` bodies keep `import Postbox` (they still
call `postbox.transaction`) and wrap raw peer values with `EnginePeer(peer)`
at the SendAsPeer constructor sites. Manual `==` body dropped in favor of
synthesized Equatable.
Consumer-side cascade in 5 files:
- 3 `._asPeer()` bridge-drops at SendAsPeer constructor sites
- 6 redundant `EnginePeer(peer.peer)` / `EnginePeer($0.peer)` wrap
drops (the field is now EnginePeer, so the wrap fails to compile)
- 1 `peer.peer as? TelegramChannel` downcast rewritten to
`if case let .channel(channel) = peer.peer` enum-pattern form
- 2 `EnginePeer(channel)` wraps added where raw `TelegramChannel` is
passed into `SendAsPeer(peer: ...)`
- 1 `(sendAsPeer?.peer).flatMap(EnginePeer.init)` simplified to
`sendAsPeer?.peer` (already `EnginePeer?`)
Files modified:
submodules/TelegramCore/Sources/TelegramEngine/Messages/SendAsPeers.swift
submodules/TelegramUI/Components/Chat/ChatSendAsContextMenu/Sources/ChatSendAsPeerListContextItem.swift
submodules/TelegramUI/Sources/Chat/ChatControllerLoadDisplayNode.swift
submodules/TelegramUI/Components/Chat/ChatTextInputPanelNode/Sources/ChatTextInputPanelComponent.swift
submodules/TelegramUI/Components/Chat/ChatTextInputPanelNode/Sources/ChatTextInputPanelNode.swift
submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerViewSendMessage.swift
Plan: docs/superpowers/plans/2026-04-24-sendaspeer-engine-peer-migration.md
Spec: docs/superpowers/specs/2026-04-24-sendaspeer-engine-peer-migration-design.md
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 10.4: Update CLAUDE.md wave counter**
Edit `CLAUDE.md` to bump the "Waves landed so far" line from "34 waves" to "35 waves" and update the "as of" date if the commit lands after 2026-04-24.
- [ ] **Step 10.5: Append wave outcome to the postbox-refactor-log**
Append a "Wave 35 outcome" section to `docs/superpowers/postbox-refactor-log.md` documenting:
- Actual files touched and edit counts vs. plan
- Any inventory undercounts surfaced by Task 8
- Any lessons learned (e.g., whether the flatMap/map simplifications were actually type-required or whether they could have been left as redundant-but-compiling wraps)
Keep concise.
- [ ] **Step 10.6: Commit the docs update**
Run:
```bash
git add CLAUDE.md docs/superpowers/postbox-refactor-log.md
git commit -m "$(cat <<'EOF'
docs: add wave 35 outcome (SendAsPeer.peer Peer→EnginePeer)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 10.7: Update the next-wave memory**
Update `/Users/isaac/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/project_postbox_refactor_next_wave.md`:
- Add wave 35 to the "Latest commits" section
- Move SendAsPeer migration from "Wave 34+ candidates → Downstream Peer-typed APIs" to landed
- Record the inventory undercount ratio (actual-files-touched ÷ pre-flight-file-count) for calibration of future Peer-typed-API waves
- Update the "Recommended wave 35" section to reflect the new wave 36 recommendation. Candidates to promote: `makePeerInfoController` (largest Peer-typed-API remaining), `ContactListPeer.peer(peer:)` case payload, `canSendMessagesToPeer(_:)` parameter, accountManager-side engine path, Shape-C resourceData module pick
Use the Edit tool on the memory file. No git commit needed (memory lives outside the repo).
---
## Risks and notes
- **Inner `peer` shadowing in ChatSendAsPeerListContextItem:73.** The original `if let peer = peer.peer as? TelegramChannel` shadows the outer `peer: SendAsPeer` loop variable. The rewrite uses `channel` to avoid shadowing. Verify every reference to `peer.info` (and any sibling field access) within the old inner-if scope is updated to `channel.*` — Step 2.1's instructions cover this, but it's easy to miss a field reference.
- **`replace_all` correctness.** Whenever the plan suggests `replace_all=true`, verify the count first via grep. If the count is unexpected, revert to per-site Edits with surrounding context.
- **Inventory undercount.** Wave 34 undercounted by ~30%. The Explore agent for wave 35 explicitly included `.peer as?`/`is`/outflow-helper patterns, so the expected ratio is lower, but budget for 1–3 inventory-missed sites surfacing in Task 8.
- **Name collisions (do NOT touch).** `[EnginePeer]` arrays in `LiveStreamSettingsScreen.swift`, `ShareWithPeersScreen.swift`, and `ChatSendStarsScreen.swift` named `sendAsPeers` / `availableSendAsPeers` are unrelated. `ChatPanelInterfaceInteraction` callbacks named `openSendAsPeer` take `(ASDisplayNode, ContextGesture?)`, not `SendAsPeer`. `initialSendAsPeerId` parameters are `PeerId`-typed. If Task 8 surfaces errors in any of these files, the fix likely indicates a wrong cascade from a real SendAsPeer site — do NOT migrate those files as part of this wave.
- **WIP isolation.** Pre-existing modifications to `ChatListFilterPresetController.swift`, `ChatListFilterPresetListController.swift`, the `sourcekit-bazel-bsp` submodule marker, and untracked `build-system/tulsi/` / `submodules/TgVoip/` / `third-party/libx264/` / `docs/superpowers/plans/2026-04-22-claude-md-reorganization.md` are user WIP — do NOT stage them. Use the explicit `git add <files>` form in Step 10.2.

116
docs/superpowers/plans/2026-04-25-clearpeerhistory-openclearhistory-engine-peer.md
View file

@ -1,116 +0,0 @@
# Wave 54: ClearPeerHistory.init + openClearHistory `chatPeer: Peer → EnginePeer`
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task.
**Goal:** Migrate the `chatPeer:` parameter type on both `ClearPeerHistory.init` and `openClearHistory` from `Peer` to `EnginePeer`. Closes wave-53's deferred sibling.
**Wave shape:** Bundled method-signature migration (familiar from waves 41/44/47/50/53). Mechanical `as?`/`is` cluster on a single field, with EnginePeer.init boundary lifts at each call site.
**Tech Stack:** Swift, Bazel, Make.py.
---
## Pre-Flight Inventory (validated 2026-04-25)
**2 files modified, 16 edits.**
### File 1: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreen.swift` (PIS)
| Line | Current | After | Note |
|---|---|---|---|
| 3213 | `func openClearHistory(... peer: Peer, chatPeer: Peer) {` | `... chatPeer: EnginePeer)` | type-site |
| 3230 | `EnginePeer(chatPeer).compactDisplayTitle` | `chatPeer.compactDisplayTitle` | drop wrap |
| 3232 | `EnginePeer(chatPeer).compactDisplayTitle` | `chatPeer.compactDisplayTitle` | drop wrap |
| 3251 | `EnginePeer(chatPeer).compactDisplayTitle` | `chatPeer.compactDisplayTitle` | drop wrap |
| 3269 | `EnginePeer(chatPeer).compactDisplayTitle` | `chatPeer.compactDisplayTitle` | drop wrap |
| 7416 | `init(... peer: Peer, chatPeer: Peer, cachedData: ...)` | `... chatPeer: EnginePeer, cachedData: ...` | type-site |
| 7421 | `} else if chatPeer is TelegramSecretChat {` | `} else if case .secretChat = chatPeer {` | conversion |
| 7425 | `} else if let group = chatPeer as? TelegramGroup {` | `} else if case let .legacyGroup(group) = chatPeer {` | conversion |
| 7436 | `} else if let channel = chatPeer as? TelegramChannel {` | `} else if case let .channel(channel) = chatPeer {` | conversion |
| 7464 | `if let user = chatPeer as? TelegramUser, user.botInfo != nil {` | `if case let .user(user) = chatPeer, user.botInfo != nil {` | conversion |
`peer:` parameter stays Peer-typed in both functions: `openClearHistory` doesn't reference `peer` in its body; `ClearPeerHistory.init` uses only `peer.id == context.account.peerId` (line 7417), which works on Peer (and would also work on EnginePeer, but migrating it would require 6 boundary lifts at PISPBA call sites for no internal benefit).
### File 2: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreenPerformButtonAction.swift` (PISPBA)
| Line | Current | After | Note |
|---|---|---|---|
| 851 | `chatPeer: chatPeer._asPeer()` | `chatPeer: chatPeer` | drop wave-53 ADD |
| 857 | `chatPeer: user` | `chatPeer: EnginePeer(user)` | boundary lift (TelegramUser) |
| 1067 | `chatPeer: channel` | `chatPeer: EnginePeer(channel)` | boundary lift (TelegramChannel) |
| 1073 | `chatPeer: channel` | `chatPeer: EnginePeer(channel)` | boundary lift (TelegramChannel) |
| 1234 | `chatPeer: group` | `chatPeer: EnginePeer(group)` | boundary lift (TelegramGroup) |
| 1240 | `chatPeer: group` | `chatPeer: EnginePeer(group)` | boundary lift (TelegramGroup) |
### Net accounting
- **Drops:** 5 (4 `EnginePeer(chatPeer).compactDisplayTitle` + 1 `_asPeer()` bridge from wave 53).
- **Adds:** 5 boundary lifts (5 `EnginePeer(...)` wraps at PISPBA call sites).
- **Conversions:** 4 (`is`/`as?` → `case let`).
- **Type-site:** 2 (signature changes on PIS:3213 and PIS:7416).
Net internal-bridge progress: `5 drops − 5 adds = 0 raw count`. But ratchet kills 4 internal display-call wraps (`EnginePeer(chatPeer).compactDisplayTitle` patterns) which is the hot path; only call-site boundary lifts remain. Closes wave-53's deferred ADD at PISPBA:851.
---
## Tasks
### Task 1: PIS signature edits + body wrap drops
- [ ] **Step 1: Edit `openClearHistory` signature at PIS:3213**
Replace `peer: Peer, chatPeer: Peer)` with `peer: Peer, chatPeer: EnginePeer)`.
- [ ] **Step 2: Drop 4 `EnginePeer(chatPeer).compactDisplayTitle` wraps**
`replace_all=true` of `EnginePeer(chatPeer).compactDisplayTitle` → `chatPeer.compactDisplayTitle`. (Only 4 occurrences in the file, all in `openClearHistory` body; verified by grep.)
- [ ] **Step 3: Edit `ClearPeerHistory.init` signature at PIS:7416**
Replace `peer: Peer, chatPeer: Peer, cachedData:` with `peer: Peer, chatPeer: EnginePeer, cachedData:`.
- [ ] **Step 4: Convert PIS:7421 `is TelegramSecretChat`**
Replace `} else if chatPeer is TelegramSecretChat {` with `} else if case .secretChat = chatPeer {`.
- [ ] **Step 5: Convert PIS:7425 `as? TelegramGroup`**
Replace `} else if let group = chatPeer as? TelegramGroup {` with `} else if case let .legacyGroup(group) = chatPeer {`.
- [ ] **Step 6: Convert PIS:7436 `as? TelegramChannel`**
Replace `} else if let channel = chatPeer as? TelegramChannel {` with `} else if case let .channel(channel) = chatPeer {`.
- [ ] **Step 7: Convert PIS:7464 `as? TelegramUser`**
Replace `if let user = chatPeer as? TelegramUser, user.botInfo != nil {` with `if case let .user(user) = chatPeer, user.botInfo != nil {`.
### Task 2: PISPBA call-site lifts + bridge drop
- [ ] **Step 1: Drop wave-53 `_asPeer()` bridge at PISPBA:851**
Replace `chatPeer: chatPeer._asPeer()` with `chatPeer: chatPeer`.
- [ ] **Step 2: Lift PISPBA:857 `chatPeer: user`**
Replace `peer: user, chatPeer: user)` with `peer: user, chatPeer: EnginePeer(user))`.
- [ ] **Step 3: Lift channel call sites (PISPBA:1067 + 1073)**
`replace_all=true` of `chatPeer: channel` → `chatPeer: EnginePeer(channel)`. Verify exactly 2 hits flipped.
- [ ] **Step 4: Lift group call sites (PISPBA:1234 + 1240)**
`replace_all=true` of `chatPeer: group` → `chatPeer: EnginePeer(group)`. Verify exactly 2 hits flipped.
### Task 3: Build verification
- [ ] **Step 1: Run full build with `--continueOnError`.**
Forecast 1 iteration. Risk: hidden `chatPeer` access on Peer-typed shape elsewhere (none expected — body audit complete).
### Task 4: Commit + log
- [ ] **Step 1: Commit wave with the two file paths explicitly.**
- [ ] **Step 2: Update `docs/superpowers/postbox-refactor-log.md` and the memory file.**
- [ ] **Step 3: Commit log.**

516
docs/superpowers/plans/2026-04-25-peerinfo-enclosingpeer-engine-peer.md
View file

@ -1,516 +0,0 @@
# Wave 50: enclosingPeer Peer? → EnginePeer? Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Migrate the PeerInfo members chain's `enclosingPeer` field from raw Postbox `Peer?` to `EnginePeer?` (wave 50 of the Postbox → TelegramEngine refactor).
**Architecture:** Cross-file private struct-field migration with stored-form ratchet. Edits stay inside `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/`. Replaces `as? TelegramChannel` / `as? TelegramGroup` casts with `case let .channel(...)` / `case let .legacyGroup(...)` (wave-41/45 idiom), drops `is TelegramChannel` checks for `case .channel = ...` (wave-41 always-false-warning fix), and removes 5 internal `_asPeer()` / `EnginePeer(...)` / `flatMap(EnginePeer.init)` bridges. The engine.data subscription at PIMP:354 already returns `EnginePeer?` — this wave closes the demote-then-promote ratchet.
**Tech Stack:** Swift, Bazel via `Make.py`, no unit tests (per `CLAUDE.md`). Verification is the full-project debug-sim-arm64 build with `--continueOnError`.
**Iteration budget:** 1–2 (target first-pass-clean; recent first-pass-clean streak: waves 42, 43*, 45, 46, 48, 49 — *wave 43 took 2 iterations).
**Note on TDD:** This project has no unit tests (CLAUDE.md "No tests are used at the moment"). The standard TDD test-first cycle in the skill template does not apply. Each task instead writes the edits, then verifies via Bazel build + residue grep.
---
## File Structure
| File | Role | Changes |
|---|---|---|
| `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/ListItems/PeerInfoScreenMemberItem.swift` (PSMI) | List-item view-model + node | Type-change stored field + init param; 4 cast/is-check rewrites; 1 `flatMap(EnginePeer.init)` simplification |
| `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/Panes/PeerInfoMembersPane.swift` (PIMP) | Members-pane node + helpers | 3 func sigs + 1 stored field type-change; 4 cast/is-check rewrites; 1 `EnginePeer(...)` wrap drop; 2 `_asPeer()` drops |
| `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoProfileItems.swift` (PSPB) | Profile-items builder (non-settings members section) | 1 boundary `_asPeer()` drop at the call site that constructs the migrated init |
No public-API ripple — `PeerInfoScreenMemberItem` and `PeerInfoMembersPaneNode` are local to the PeerInfoScreen module.
---
## Task 1: PSMI.swift — type changes + cast/is-check rewrites + flatMap simplification
**Files:**
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/ListItems/PeerInfoScreenMemberItem.swift`
**Edits in this task:** 7 (1 stored-field type, 1 init-param type, 2 cast→case-let, 2 is→case, 1 flatMap simplification).
- [ ] **Step 1: Change stored field type at line 23**
Find:
```swift
let enclosingPeer: Peer?
```
Replace with:
```swift
let enclosingPeer: EnginePeer?
```
- [ ] **Step 2: Change init parameter type at line 34**
Find:
```swift
enclosingPeer: Peer?,
```
Replace with:
```swift
enclosingPeer: EnginePeer?,
```
- [ ] **Step 3: Rewrite cast at line 152 (TelegramChannel)**
Find:
```swift
if let channel = item.enclosingPeer as? TelegramChannel, channel.hasPermission(.editRank) {
```
Replace with:
```swift
if case let .channel(channel) = item.enclosingPeer, channel.hasPermission(.editRank) {
```
- [ ] **Step 4: Rewrite cast at line 154 (TelegramGroup)**
Find:
```swift
} else if let group = item.enclosingPeer as? TelegramGroup, !group.hasBannedPermission(.banEditRank) {
```
Replace with:
```swift
} else if case let .legacyGroup(group) = item.enclosingPeer, !group.hasBannedPermission(.banEditRank) {
```
- [ ] **Step 5: Simplify flatMap at line 178**
Find:
```swift
let actions = availableActionsForMemberOfPeer(accountPeerId: item.context.accountPeerId, peer: item.enclosingPeer.flatMap(EnginePeer.init), member: item.member)
```
Replace with:
```swift
let actions = availableActionsForMemberOfPeer(accountPeerId: item.context.accountPeerId, peer: item.enclosingPeer, member: item.member)
```
- [ ] **Step 6: Rewrite is-check at line 181**
Find:
```swift
if actions.contains(.promote) && item.enclosingPeer is TelegramChannel {
```
Replace with:
```swift
if actions.contains(.promote), case .channel = item.enclosingPeer {
```
- [ ] **Step 7: Rewrite is-check at line 187**
Find:
```swift
if item.enclosingPeer is TelegramChannel {
```
Replace with:
```swift
if case .channel = item.enclosingPeer {
```
---
## Task 2: PIMP.swift — signatures + stored field + body rewrites + demotion drops
**Files:**
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/Panes/PeerInfoMembersPane.swift`
**Edits in this task:** 11 (3 func sigs + 1 stored-field type + 4 cast/is rewrites + 1 EnginePeer wrap drop + 2 `_asPeer()` drops).
- [ ] **Step 1: Change `func item(...)` signature at line 92**
Find:
```swift
func item(context: AccountContext, presentationData: PresentationData, enclosingPeer: Peer, addMemberAction: @escaping () -> Void, action: @escaping (PeerInfoMember, PeerMembersListAction) -> Void, contextAction: ((PeerInfoMember, ASDisplayNode, ContextGesture?) -> Void)?) -> ListViewItem {
```
Replace with:
```swift
func item(context: AccountContext, presentationData: PresentationData, enclosingPeer: EnginePeer, addMemberAction: @escaping () -> Void, action: @escaping (PeerInfoMember, PeerMembersListAction) -> Void, contextAction: ((PeerInfoMember, ASDisplayNode, ContextGesture?) -> Void)?) -> ListViewItem {
```
- [ ] **Step 2: Rewrite cast at line 113 (TelegramChannel, non-optional context)**
Find:
```swift
if let channel = enclosingPeer as? TelegramChannel, channel.hasPermission(.editRank) {
```
Replace with:
```swift
if case let .channel(channel) = enclosingPeer, channel.hasPermission(.editRank) {
```
- [ ] **Step 3: Rewrite cast at line 115 (TelegramGroup, non-optional context)**
Find:
```swift
} else if let group = enclosingPeer as? TelegramGroup, !group.hasBannedPermission(.banEditRank) {
```
Replace with:
```swift
} else if case let .legacyGroup(group) = enclosingPeer, !group.hasBannedPermission(.banEditRank) {
```
- [ ] **Step 4: Drop the `EnginePeer(...)` wrap at line 139**
Find:
```swift
let actions = availableActionsForMemberOfPeer(accountPeerId: context.account.peerId, peer: EnginePeer(enclosingPeer), member: member)
```
Replace with:
```swift
let actions = availableActionsForMemberOfPeer(accountPeerId: context.account.peerId, peer: enclosingPeer, member: member)
```
`availableActionsForMemberOfPeer` takes `peer: EnginePeer?` (PeerInfoData.swift:2314); Swift auto-wraps the non-optional `enclosingPeer: EnginePeer` to optional.
- [ ] **Step 5: Rewrite is-check at line 142 (non-optional context)**
Find:
```swift
if actions.contains(.promote) && enclosingPeer is TelegramChannel {
```
Replace with:
```swift
if actions.contains(.promote), case .channel = enclosingPeer {
```
- [ ] **Step 6: Rewrite is-check at line 148 (non-optional context)**
Find:
```swift
if enclosingPeer is TelegramChannel {
```
Replace with:
```swift
if case .channel = enclosingPeer {
```
- [ ] **Step 7: Change `preparedTransition` signature at line 271**
Find:
```swift
private func preparedTransition(from fromEntries: [PeerMembersListEntry], to toEntries: [PeerMembersListEntry], context: AccountContext, presentationData: PresentationData, enclosingPeer: Peer, addMemberAction: @escaping () -> Void, action: @escaping (PeerInfoMember, PeerMembersListAction) -> Void, contextAction: ((PeerInfoMember, ASDisplayNode, ContextGesture?) -> Void)?) -> PeerMembersListTransaction {
```
Replace with:
```swift
private func preparedTransition(from fromEntries: [PeerMembersListEntry], to toEntries: [PeerMembersListEntry], context: AccountContext, presentationData: PresentationData, enclosingPeer: EnginePeer, addMemberAction: @escaping () -> Void, action: @escaping (PeerInfoMember, PeerMembersListAction) -> Void, contextAction: ((PeerInfoMember, ASDisplayNode, ContextGesture?) -> Void)?) -> PeerMembersListTransaction {
```
- [ ] **Step 8: Change stored field type at line 293**
Find:
```swift
private var enclosingPeer: Peer?
```
Replace with:
```swift
private var enclosingPeer: EnginePeer?
```
- [ ] **Step 9: Drop `_asPeer()` at line 361**
Find:
```swift
strongSelf.enclosingPeer = enclosingPeer._asPeer()
```
Replace with:
```swift
strongSelf.enclosingPeer = enclosingPeer
```
- [ ] **Step 10: Drop `_asPeer()` at line 363**
Find:
```swift
strongSelf.updateState(enclosingPeer: enclosingPeer._asPeer(), state: state, presentationData: presentationData)
```
Replace with:
```swift
strongSelf.updateState(enclosingPeer: enclosingPeer, state: state, presentationData: presentationData)
```
- [ ] **Step 11: Change `updateState` signature at line 442**
Find:
```swift
private func updateState(enclosingPeer: Peer, state: PeerInfoMembersState, presentationData: PresentationData) {
```
Replace with:
```swift
private func updateState(enclosingPeer: EnginePeer, state: PeerInfoMembersState, presentationData: PresentationData) {
```
The pass-through call sites at PIMP:275, :276, :437, :438, :451, :485 require no edit — types flow through transparently.
---
## Task 3: PSPB.swift — boundary lift at members-section call site
**Files:**
- Modify: `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoProfileItems.swift`
**Edits in this task:** 1.
- [ ] **Step 1: Drop `_asPeer()` at line 852**
Find:
```swift
items[.peerMembers]!.append(PeerInfoScreenMemberItem(id: member.id, context: .account(context), enclosingPeer: peer._asPeer(), member: member, isAccount: false, action: isAccountPeer ? { _ in
```
Replace with:
```swift
items[.peerMembers]!.append(PeerInfoScreenMemberItem(id: member.id, context: .account(context), enclosingPeer: peer, member: member, isAccount: false, action: isAccountPeer ? { _ in
```
`peer` here is the closure-bound `EnginePeer` from the `data.peer` source pipeline (`PeerInfoScreenData.peer: EnginePeer?` post-wave-42, unwrapped to non-optional `EnginePeer` and being passed to a now-`EnginePeer?` param — auto-promotes to optional).
The other `PeerInfoScreenMemberItem(...)` construction at `PeerInfoSettingsItems.swift:132` passes `enclosingPeer: nil`, which is valid for either optional type — no edit.
---
## Task 4: Full-project Bazel build
**Files:** none (verification only).
- [ ] **Step 1: Run the build with `--continueOnError`**
Run:
```sh
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent \
--buildNumber=1 --configuration=debug_sim_arm64 --continueOnError
```
Expected: clean build (`bazel build complete` or equivalent green output).
- [ ] **Step 2: If build fails, triage iteration**
If errors land in `PeerInfoScreenMemberItem.swift` or `PeerInfoMembersPane.swift` or `PeerInfoProfileItems.swift`:
- Read the failing line.
- Common failure modes from prior waves:
- **Always-false `is` warning under `-warnings-as-errors`**: leftover `is TelegramX` not converted in step. Re-grep `enclosingPeer is Telegram` over the 3 files.
- **Always-failing `as?` cast warning**: leftover `as? TelegramX` not converted. Re-grep `enclosingPeer.*as\?`.
- **Type mismatch on closure-capture alias**: a `strongSelf.enclosingPeer` or `self.enclosingPeer` site missed a `_asPeer()` drop. Re-grep `enclosingPeer\._asPeer\|EnginePeer\(enclosingPeer`.
- **Unused variable warning**: a binding from `case let .channel(channel)` not actually used. Re-read the body.
Fix in place and re-run step 1. Budget: 2 iterations.
If errors land outside those 3 files: **STOP**. The wave was supposed to be self-contained. Re-read the spec, identify the missed call site, decide whether to add it or abandon the wave.
---
## Task 5: Post-edit residue grep
**Files:** none (verification only).
- [ ] **Step 1: Bridge residue grep**
Run:
```sh
grep -rnE "enclosingPeer\._asPeer|EnginePeer\(enclosingPeer\)|enclosingPeer\.flatMap\(EnginePeer" \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/
```
Expected: empty output.
- [ ] **Step 2: Cast/is-check residue grep**
Run:
```sh
grep -rnE "enclosingPeer.*as\? TelegramChannel|enclosingPeer.*as\? TelegramGroup|enclosingPeer is TelegramChannel" \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/
```
Expected: empty output.
- [ ] **Step 3: Sanity check — `enclosingPeer` references should now exclusively type-resolve to EnginePeer**
Run:
```sh
grep -nE ": Peer\b" submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/ListItems/PeerInfoScreenMemberItem.swift submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/Panes/PeerInfoMembersPane.swift
```
Expected: no `enclosingPeer: Peer` or `enclosingPeer: Peer?` annotations remain. (Other `: Peer` annotations on unrelated symbols are fine.)
---
## Task 6: Commit the wave
**Files:** none (git only).
- [ ] **Step 1: Stage the 3 modified files**
```sh
git add \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/ListItems/PeerInfoScreenMemberItem.swift \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/Panes/PeerInfoMembersPane.swift \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoProfileItems.swift
```
- [ ] **Step 2: Confirm staging is clean**
```sh
git status --short | grep -v "^??"
```
Expected output: only the 3 staged files (lines starting with `M ` or `A `). If other modified files appear, they predate the wave (per CLAUDE.md memory: build-system/bazel-rules/sourcekit-bazel-bsp submodule marker is pre-existing WIP).
- [ ] **Step 3: Commit**
```sh
git commit -m "$(cat <<'EOF'
Postbox -> TelegramEngine wave 50
Migrate enclosingPeer Peer? -> EnginePeer? across PeerInfoScreenMemberItem
+ PeerInfoMembersPaneNode + 1 PSPB call site. 19 edits / 3 files.
Drops 5 internal bridges: 2 _asPeer() demotions at PIMP:361/363, 1
EnginePeer(enclosingPeer) wrap at PIMP:139, 1 flatMap(EnginePeer.init)
at PSMI:178, 1 boundary _asPeer() lift at PSPB:852.
Closes the wave-48-pattern internal-demotion-and-external-re-promotion
ratchet at PIMP:354-363 (engine.data subscription returns EnginePeer?,
previously demoted to Peer? at storage).
All `as? TelegramChannel` / `as? TelegramGroup` casts converted to
`case let .channel(...)` / `case let .legacyGroup(...)` (wave-41/45
idiom). All `is TelegramChannel` checks converted to
`case .channel = ...` (wave-41 always-false-warning fix).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 4: Verify commit**
```sh
git log --oneline -1
```
Expected: shows the wave 50 commit.
---
## Task 7: Update outcome log + memory
**Files:**
- Modify: `docs/superpowers/postbox-refactor-log.md`
- Modify: `~/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/project_postbox_refactor_next_wave.md`
- [ ] **Step 1: Append wave 50 outcome to refactor log**
Add a "Wave 50 outcome" entry at the appropriate chronological position in `docs/superpowers/postbox-refactor-log.md`. Use the wave 49 outcome entry as the template. Include:
- Commit hash (from Task 6 step 4).
- Iteration count (1 if first-pass-clean; 2 if Task 4 step 2 fired once).
- Net-bridge accounting: −5 internal bridges (2 `_asPeer()` + 1 `EnginePeer(...)` wrap + 1 `flatMap(EnginePeer.init)` + 1 boundary `_asPeer()` lift). 0 ADD wraps. 0 boundary lifts net new.
- Bazel build duration (from Task 4 step 1 output).
- Any wave-specific lessons surfaced.
- [ ] **Step 2: Update wave-50-next-wave memory**
Edit `~/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/project_postbox_refactor_next_wave.md`:
- Promote wave 50 outcome line into the "Latest commits" section using the format of the wave 49 entry.
- Update the top frontmatter `description` to reflect wave 50 landed and propose wave 51.
- Promote the wave-51 candidate (`PeerInfoGroupsInCommonPaneNode.PeerEntry.peer: Peer → EnginePeer`) to the top of the "Wave 51 candidates" section, replacing the now-stale "Wave 50 candidates" header. Re-run the broader grep if needed:
```sh
grep -rnE "^\s*(let|var|public let|public var|private let|private var) [a-zA-Z_]+: Peer\??$|^\s*(let|var|public let|public var|private let|private var) [a-zA-Z_]+: Peer\? = " \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/ --include="*.swift" | grep -v "EnginePeer"
```
- [ ] **Step 3: Commit the doc update**
```sh
git add docs/superpowers/postbox-refactor-log.md
git commit -m "$(cat <<'EOF'
docs: log wave 50 outcome
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
(Memory file updates are not committed — they live outside the repo.)
---
## Net delta projection (from spec)
| Category | Count | Sites |
|---|---|---|
| Internal bridge drops | −5 | PIMP:361, PIMP:363, PIMP:139, PSMI:178, PSPB:852 |
| Boundary lifts (net new) | 0 | source pipeline already EnginePeer? |
| ADD wraps | 0 | no Peer-only property accesses on bare `enclosingPeer` |
| Cast→case-let conversions | 4 | PSMI:152/154, PIMP:113/115 |
| `is`→`case` conversions | 4 | PSMI:181/187, PIMP:142/148 |
| Type annotations updated | 6 | PSMI:23/34, PIMP:92/271/293/442 |
**Total commit footprint:** 19 line edits across 3 files, plus a docs commit for the outcome log.

106
docs/superpowers/plans/2026-04-25-peerinfoscreendata-linked-peers-engine-peer.md
View file

@ -1,106 +0,0 @@
# Wave 49 — `PeerInfoScreenData.linkedDiscussionPeer` + `.linkedMonoforumPeer` `Peer? → EnginePeer?` (bundle)
**Date:** 2026-04-25
**Predecessor:** Wave 48 (commit `1e4c2eea33`) — savedMessagesPeer single-field migration.
**Shape:** Cross-file bundled struct-field migration (2 sibling fields, 2 files). Both fields are module-internal; no external consumer references them on `PeerInfoScreenData`. Bundled because both fields:
- Share a sibling declaration site in `PeerInfoData.swift`.
- Have parallel local-source patterns (raw `Peer?` from `peerView.peers[id]` dict lookup; **not** an engine signal as in wave 48).
- Are both consumed in `PeerInfoProfileItems.swift` only.
- Migrating one without the other adds friction at the source-construction sites where they're computed together.
## Pre-flight inventory
`grep -rEn "(\w+\??)\.linkedDiscussionPeer\b|(\w+\??)\.linkedMonoforumPeer\b" submodules/ Telegram/`:
- `submodules/PeerInfoUI/Sources/ChannelDiscussionGroupSetupController.swift:600,651` — references are on a local `view` object (different type, NOT PeerInfoScreenData). Out of scope.
- All `data.linkedDiscussionPeer` / `data.linkedMonoforumPeer` accesses live in PIPI within the PeerInfoScreen module.
Within scope:
### `PeerInfoData.swift` (storage class + 2 init sites that compute the locals)
| Site | Code | Action |
|------|------|--------|
| :396 | `let linkedDiscussionPeer: Peer?` (field decl) | Type → `EnginePeer?` |
| :397 | `let linkedMonoforumPeer: Peer?` (field decl) | Type → `EnginePeer?` |
| :453 | `linkedDiscussionPeer: Peer?,` (init param) | Type → `EnginePeer?` |
| :454 | `linkedMonoforumPeer: Peer?,` (init param) | Type → `EnginePeer?` |
| :498 | `self.linkedDiscussionPeer = linkedDiscussionPeer` | No change |
| :499 | `self.linkedMonoforumPeer = linkedMonoforumPeer` | No change |
| :1038, :1111, :1631 | `linkedDiscussionPeer: nil,` (init kwargs) | No change |
| :1039, :1112, :1632 | `linkedMonoforumPeer: nil,` (init kwargs) | No change |
| :1836 | `var discussionPeer: Peer?` (local) | Type → `EnginePeer?` |
| :1838 | `discussionPeer = peer` (where `peer = peerView.peers[linkedDiscussionPeerId]`, raw `Peer`) | Wrap → `discussionPeer = EnginePeer(peer)` |
| :1841 | `var monoforumPeer: Peer?` (local) | Type → `EnginePeer?` |
| :1843 | `monoforumPeer = peerView.peers[linkedMonoforumId]` (dict lookup, `Peer?`) | Wrap → `monoforumPeer = peerView.peers[linkedMonoforumId].flatMap(EnginePeer.init)` |
| :2131 | `var discussionPeer: Peer?` (local, parallel to :1836) | Type → `EnginePeer?` |
| :2133 | `discussionPeer = peer` (parallel to :1838) | Wrap → `discussionPeer = EnginePeer(peer)` |
| :2136 | `var monoforumPeer: Peer?` (local, parallel to :1841) | Type → `EnginePeer?` |
| :2138 | `monoforumPeer = peerView.peers[linkedMonoforumId]` (parallel to :1843) | Wrap with `.flatMap(EnginePeer.init)` |
| :1878, :1879, :2216, :2217 | init kwargs `linkedDiscussionPeer: discussionPeer,` / `linkedMonoforumPeer: monoforumPeer,` | No change (locals migrate; pass through) |
That's **12 edits** in PID. Note the `var` declarations and assignments at :1836–:1843 and :2131–:2138 are *parallel pairs* (verified by grep). Use `replace_all=true` for the duplicate snippets.
### `PeerInfoProfileItems.swift` (3 edits)
| Site | Code | Action |
|------|------|--------|
| :1098 | `if let peer = data.linkedDiscussionPeer { ... }` | No change (binding works on `EnginePeer?`) |
| :1099 | `if let addressName = peer.addressName, !addressName.isEmpty {` | No change — `EnginePeer.addressName` forwarded (verified at `submodules/TelegramCore/Sources/TelegramEngine/Peers/Peer.swift:461`) |
| :1102 | `discussionGroupTitle = EnginePeer(peer).displayTitle(strings: ..., displayOrder: ...)` | **Drop wrap** → `peer.displayTitle(...)` |
| :1197 | `if let monoforumPeer = data.linkedMonoforumPeer as? TelegramChannel {` | **Pattern rewrite** → `if case let .channel(monoforumPeer) = data.linkedMonoforumPeer {` |
| :1198 | `monoforumPeer.sendPaidMessageStars` | No change — `sendPaidMessageStars` is a `TelegramChannel` property (`SyncCore_TelegramChannel.swift:215`); `case .channel` binds to `TelegramChannel` |
| :1404 | `if let linkedDiscussionPeer = data.linkedDiscussionPeer {` | No change (binding works) |
| :1406 | `if let addressName = linkedDiscussionPeer.addressName, !addressName.isEmpty {` | No change (forwarded) |
| :1409 | `peerTitle = EnginePeer(linkedDiscussionPeer).displayTitle(...)` | **Drop wrap** → `linkedDiscussionPeer.displayTitle(...)` |
3 edits in PIPI.
## EnginePeer property forwarding audit
- `EnginePeer.addressName` — forwarded at `Peer.swift:461`. ✓
- `EnginePeer.displayTitle(strings:displayOrder:)` — defined as `EnginePeer` instance method (used elsewhere via `EnginePeer(...).displayTitle(...)` pattern; once we have an `EnginePeer`, it's directly callable). ✓
- `case .channel` binding payload is `TelegramChannel`. ✓
- `TelegramChannel.sendPaidMessageStars` — exists (`SyncCore_TelegramChannel.swift:215`). ✓
## Net bridge count
- **ADDs (4):** boundary lifts at PID:1838 (`EnginePeer(peer)`), PID:1843 (`.flatMap(EnginePeer.init)`), PID:2133, PID:2138. These lift the Postbox-typed `peerView.peers[...]` value to the engine type at the boundary — the correct semantic position for a Postbox→Engine refactor (mirrors wave 42 where `peer.flatMap(EnginePeer.init)` lift was added at PID:1620).
- **DROPs (2):** PIPI:1102 and :1409 lose `EnginePeer(...)` wraps around `displayTitle` calls.
- **Net text bridges:** +2. **But:** the ADDs are correct boundary lifts; the field-typed-as-`EnginePeer?` is the canonical state. The 2 displayTitle DROPs are the actual ratchet value.
- **Plus:** 1 cleaner pattern (PIPI:1197 `as?` cast → `case let .channel`), no text saving but better Swift idiom.
## Edit list
### `PeerInfoData.swift` (12 edits, but Edit text uses `replace_all=true` to bundle parallel pairs)
1. Line 396: `let linkedDiscussionPeer: Peer?` → `let linkedDiscussionPeer: EnginePeer?`
2. Line 397: `let linkedMonoforumPeer: Peer?` → `let linkedMonoforumPeer: EnginePeer?`
3. Line 453: `linkedDiscussionPeer: Peer?,` → `linkedDiscussionPeer: EnginePeer?,`
4. Line 454: `linkedMonoforumPeer: Peer?,` → `linkedMonoforumPeer: EnginePeer?,`
5. Lines 1836 + 2131 (`replace_all=true` over `var discussionPeer: Peer?`): → `var discussionPeer: EnginePeer?`
6. Lines 1838 + 2133 (`replace_all=true` over `discussionPeer = peer`): → `discussionPeer = EnginePeer(peer)`
7. Lines 1841 + 2136 (`replace_all=true` over `var monoforumPeer: Peer?`): → `var monoforumPeer: EnginePeer?`
8. Lines 1843 + 2138 (`replace_all=true` over `monoforumPeer = peerView.peers[linkedMonoforumId]`): → `monoforumPeer = peerView.peers[linkedMonoforumId].flatMap(EnginePeer.init)`
### `PeerInfoProfileItems.swift` (3 edits)
9. Line 1102: `discussionGroupTitle = EnginePeer(peer).displayTitle(strings: presentationData.strings, displayOrder: presentationData.nameDisplayOrder)` → `discussionGroupTitle = peer.displayTitle(strings: presentationData.strings, displayOrder: presentationData.nameDisplayOrder)`
10. Line 1197: `if let monoforumPeer = data.linkedMonoforumPeer as? TelegramChannel {` → `if case let .channel(monoforumPeer) = data.linkedMonoforumPeer {`
11. Line 1409: `peerTitle = EnginePeer(linkedDiscussionPeer).displayTitle(strings: presentationData.strings, displayOrder: presentationData.nameDisplayOrder)` → `peerTitle = linkedDiscussionPeer.displayTitle(strings: presentationData.strings, displayOrder: presentationData.nameDisplayOrder)`
## Out of scope
- `PeerInfoScreenData.chatPeer` — large blast radius. Defer.
- `PeerInfoScreenMemberItem.enclosingPeer`. Defer.
## Build & verify
Standard Bazel command. Expected 1 iteration if forwarding audit holds; 2 if a `displayTitle` overload-resolution surprise surfaces.
## Commit
`Postbox -> TelegramEngine wave 49`. Body: bundle + edits summary + ADD/DROP accounting.
## Outcome capture
Append Wave 49 entry to `docs/superpowers/postbox-refactor-log.md`; update memory file.

70
docs/superpowers/plans/2026-04-25-peerinfoscreendata-savedmessagespeer-engine-peer.md
View file

@ -1,70 +0,0 @@
# Wave 48 — `PeerInfoScreenData.savedMessagesPeer` `Peer? → EnginePeer?`
**Date:** 2026-04-25
**Predecessor:** Wave 47 (commit `d7b7536440`) — stored PHN.peer single-file private migration.
**Shape:** Cross-file struct-field migration. Storage class is internal to PeerInfoScreen module; no external consumer references PSD.savedMessagesPeer.
## Target
`submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoData.swift`, `PeerInfoScreenData.savedMessagesPeer: Peer?` at line 388.
## Pre-flight inventory
`grep -rEn "(\w+\??)\.savedMessagesPeer\b" submodules/ Telegram/` → matches only inside `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/`. No external consumer. The same field name appears in unrelated places (TelegramEngineMessages.swift, ChatListUI, etc.) but those are different declarations on different types.
Within PeerInfoScreen module:
| Site | Code | Action |
|------|------|--------|
| `PeerInfoData.swift:388` | `let savedMessagesPeer: Peer?` (struct field decl) | Type change → `EnginePeer?` |
| `PeerInfoData.swift:444` | `savedMessagesPeer: Peer?,` (init param) | Type change → `EnginePeer?` |
| `PeerInfoData.swift:489` | `self.savedMessagesPeer = savedMessagesPeer` (assignment) | No change (passthrough) |
| `PeerInfoData.swift:1029` | `savedMessagesPeer: nil,` (init kwarg) | No change (`nil` works for either) |
| `PeerInfoData.swift:1102` | `savedMessagesPeer: nil,` | No change |
| `PeerInfoData.swift:1313–1317` | `let savedMessagesPeer: Signal<EnginePeer?, NoError>` (local) | No change — already `EnginePeer?` |
| `PeerInfoData.swift:1622` | `savedMessagesPeer: savedMessagesPeer?._asPeer(),` | **Drop bridge** → `savedMessagesPeer: savedMessagesPeer,` |
| `PeerInfoData.swift:1869` | `savedMessagesPeer: nil,` | No change |
| `PeerInfoData.swift:2207` | `savedMessagesPeer: nil,` | No change |
| `PeerInfoScreen.swift:5399` | `peer: self.data?.savedMessagesPeer.flatMap(EnginePeer.init) ?? self.data?.peer,` | **Drop bridge** → `peer: self.data?.savedMessagesPeer ?? self.data?.peer,` |
| `PeerInfoScreen.swift:5805` | same as :5399 | Same drop |
Total edits: 5 (3 in PID, 2 in PIS).
## EnginePeer / read-site audit
The local signal at `PeerInfoData.swift:1313` already produces `EnginePeer?` from `engine.data.subscribe(TelegramEngine.EngineData.Item.Peer.Peer(...))`. The `?._asPeer()` at line 1622 was an artificial demotion. Migrating the field type to `EnginePeer?` removes both the demotion at the storage site and the `flatMap(EnginePeer.init)` re-promotions at the read sites — a clean ratchet.
PIS:5399 and :5805 use the field as input to `headerNode.update(... peer: ...)`, whose `peer` parameter has been `EnginePeer?` since wave 45. The `??` coalescing operand is `self.data?.peer` (already `EnginePeer?`). Result: drop the `.flatMap(EnginePeer.init)` and the expression compiles.
## Edit list
### PeerInfoData.swift (3 edits)
1. Line 388: `let savedMessagesPeer: Peer?` → `let savedMessagesPeer: EnginePeer?`
2. Line 444: `savedMessagesPeer: Peer?,` → `savedMessagesPeer: EnginePeer?,`
3. Line 1622: `savedMessagesPeer: savedMessagesPeer?._asPeer(),` → `savedMessagesPeer: savedMessagesPeer,`
### PeerInfoScreen.swift (2 edits, identical text)
4. Line 5399: `peer: self.data?.savedMessagesPeer.flatMap(EnginePeer.init) ?? self.data?.peer,` → `peer: self.data?.savedMessagesPeer ?? self.data?.peer,`
5. Line 5805: same
Use `replace_all=true` for the PIS edit since the matched text appears at both call sites verbatim.
## Out of scope
- `PeerInfoScreenData.chatPeer` — large blast radius (5 `as? TelegramX` checks downstream + ClearPeerHistory init parameter), defer.
- `PeerInfoScreenData.linkedDiscussionPeer`, `linkedMonoforumPeer` — both have `as? TelegramChannel` consumer sites in `PeerInfoProfileItems.swift`. Defer.
- `PeerInfoScreenMemberItem.enclosingPeer` — defer (separate target).
## Build & verify
Same Bazel command as wave 47. Expected 1-iteration first-pass-clean (single-pattern bridge removal, no enum-case rewrites, no Peer-only property access).
## Commit
`Postbox -> TelegramEngine wave 48`. Body lists the 5-edit summary and notes −3 internal bridges (1 PID + 2 PIS, identical PIS text appears twice).
## Outcome capture
Append a Wave 48 entry to `docs/superpowers/postbox-refactor-log.md` and update memory file `project_postbox_refactor_next_wave.md`.

62
docs/superpowers/plans/2026-04-25-phn-peer-stored-field-engine-peer.md
View file

@ -1,62 +0,0 @@
# Wave 47 — `PeerInfoHeaderNode.peer` stored field `Peer? → EnginePeer?`
**Date:** 2026-04-25
**Predecessor:** Wave 46 (commit `5ca99da5a7`) — PeerInfo avatar chain.
**Shape:** Single-file stored-field type migration. No external API change (field is `private`).
## Target
`submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoHeaderNode.swift`, stored field `private var peer: Peer?` at line 92.
## Pre-flight inventory
`grep -n "self\.peer\b" PeerInfoHeaderNode.swift` returns exactly 3 references:
| Line | Code | Site type | Action |
|------|------|-----------|--------|
| 426 | `if let peer = self.peer, peer.profileImageRepresentations.isEmpty && gallery {` | Read | None — `profileImageRepresentations` is forwarded by `EnginePeer` (see `submodules/TelegramCore/Sources/TelegramEngine/Peers/Peer.swift:485`). Compiles unchanged. |
| 521 | `self.peer = peer?._asPeer()` | Assignment | Drop the bridge → `self.peer = peer`. The `peer` parameter is already `EnginePeer?` after wave 45. |
| 2049–2054 | `guard let self, let peer = self.peer, ...` followed by `peer: EnginePeer(peer),` | Read | Drop the wrap at line 2054 → `peer: peer,`. |
External access check: `grep -rn "headerNode\.peer\b" submodules/ Telegram/` returns empty. The field is private; only same-file siblings touch it.
EnginePeer forwarding (re-confirmed at plan time):
- `profileImageRepresentations` — forwarded (Peer.swift:485). ✓
- `EnginePeer(peer)` (PHN:2054) — accepts `EnginePeer` directly when the local is already `EnginePeer`; drop the constructor.
Field-declaration change is the only "type" change needed. The 3 callers' adjustments are mechanical bridge drops.
## Edit list
1. Line 92: `private var peer: Peer?` → `private var peer: EnginePeer?`
2. Line 521: `self.peer = peer?._asPeer()` → `self.peer = peer`
3. Line 2054: `peer: EnginePeer(peer),` → `peer: peer,`
Total: 3 edits in 1 file.
## Out of scope
- `PeerInfoData.swift:355,487` — different classes' `self.peer` assignments (different types). Audit confirms these are `RenderedChannelParticipant.peer` and similar — already migrated in earlier waves or owned by other types.
- `PeerInfoAvatarTransformContainerNode.peer` (line 223) — already `EnginePeer?` after wave 46.
## Build & verify
```sh
source ~/.zshrc 2>/dev/null; \
python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent \
--buildNumber=1 --configuration=debug_sim_arm64
```
Expected: 1-iteration first-pass-clean. Only PeerInfoScreen + TelegramUI recompile.
## Commit
`Postbox -> TelegramEngine wave 47`. Body lists the 3-edit summary and notes -3 internal bridges.
## Outcome capture
Append a Wave 47 entry to `docs/superpowers/postbox-refactor-log.md` and update memory file `project_postbox_refactor_next_wave.md`.

347
docs/superpowers/plans/2026-04-26-postbox-wave-103-chat-recent-actions-controller-node.md
View file

@ -1,347 +0,0 @@
# Wave 103: ChatRecentActionsControllerNode peer Peer → EnginePeer Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Migrate `ChatRecentActionsControllerNode`'s stored `peer: Peer` field to `EnginePeer`, dropping the `_asPeer()` boundary call at the single caller site (wave 103 of the Postbox → TelegramEngine refactor).
**Architecture:** Wave-71-shadow close. Single-file private stored-form migration plus a 1-line caller drop. The caller (`ChatRecentActionsController`) already holds `peer: EnginePeer` and demotes once before passing into the node init. The wave drops the demotion and rewrites 3 `as? TelegramChannel` downcasts inside the node body to `case let .channel(...)` (wave-41/45 idiom). All scope is within `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/`.
**Tech Stack:** Swift, Bazel via `Make.py`, no unit tests (per `CLAUDE.md`). Verification is the full-project debug-sim-arm64 build.
**Iteration budget:** 1 (target first-pass-clean given the 7-edit scope and validated pre-flight grep).
**Note on TDD:** This project has no unit tests. The standard TDD test-first cycle does not apply. Each task writes the edits, then verifies via Bazel build + residue grep.
---
## File Structure
| File | Role | Changes |
|---|---|---|
| `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsControllerNode.swift` (CRACN) | Recent-actions screen controller node | Drop `import Postbox`, retype stored field + init param, rewrite 3 `as? TelegramChannel` downcasts (6 edits) |
| `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsController.swift` (CRAC) | Recent-actions screen controller (caller) | Drop `_asPeer()` at the node init (1 edit) |
No public-API ripple — `ChatRecentActionsControllerNode` is local to the module and has a single caller verified by grep.
---
## Task 1: CRACN.swift — drop `import Postbox` + type changes + downcast rewrites
**Files:**
- Modify: `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsControllerNode.swift`
**Edits in this task:** 6 (1 import drop, 1 stored-field retype, 1 init-param retype, 3 cast → case-let).
- [ ] **Step 1: Drop `import Postbox` at line 5**
Find:
```swift
import Postbox
```
Replace with: (delete the line entirely)
This file imports `TelegramCore` at line 4, which provides the `EnginePeer` type and the typealiases needed for the rest of this task.
- [ ] **Step 2: Retype stored field at line 46**
Find:
```swift
private let peer: Peer
```
Replace with:
```swift
private let peer: EnginePeer
```
- [ ] **Step 3: Retype init parameter at line 111**
Find:
```swift
init(context: AccountContext, controller: ChatRecentActionsController, peer: Peer, presentationData: PresentationData, pushController: @escaping (ViewController) -> Void, presentController: @escaping (ViewController, PresentationContextType, Any?) -> Void, getNavigationController: @escaping () -> NavigationController?) {
```
Replace with:
```swift
init(context: AccountContext, controller: ChatRecentActionsController, peer: EnginePeer, presentationData: PresentationData, pushController: @escaping (ViewController) -> Void, presentController: @escaping (ViewController, PresentationContextType, Any?) -> Void, getNavigationController: @escaping () -> NavigationController?) {
```
- [ ] **Step 4: Rewrite downcast at line 899**
Find:
```swift
if let peer = strongSelf.peer as? TelegramChannel {
```
Replace with:
```swift
if case let .channel(peer) = strongSelf.peer {
```
The bound name `peer` is preserved so the inner block (`switch peer.info { case .group: ... }`) ports verbatim. `case let .channel(peer)` binds `peer: TelegramChannel` directly (the associated value of `EnginePeer.channel`).
- [ ] **Step 5: Rewrite downcast at line 948**
Find:
```swift
if let channel = self.peer as? TelegramChannel, case .broadcast = channel.info {
```
Replace with:
```swift
if case let .channel(channel) = self.peer, case .broadcast = channel.info {
```
The compound condition (`, case .broadcast = channel.info`) ports verbatim because the bound `channel` is still `TelegramChannel`-typed.
- [ ] **Step 6: Rewrite downcast at line 1088**
Find:
```swift
if let channel = self.peer as? TelegramChannel {
```
Replace with:
```swift
if case let .channel(channel) = self.peer {
```
The inner block (`channel.hasPermission(.banMembers)`, `case .broadcast = channel.info`) ports verbatim.
The `self.peer.id` accesses at lines 145, 161, 1138, 1490 require no edit — `EnginePeer.id` is a typealiased `PeerId`, identical at the call sites.
---
## Task 2: CRAC.swift — drop boundary `_asPeer()`
**Files:**
- Modify: `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsController.swift`
**Edits in this task:** 1.
- [ ] **Step 1: Drop `_asPeer()` at line 277**
Find:
```swift
self.displayNode = ChatRecentActionsControllerNode(context: self.context, controller: self, peer: self.peer._asPeer(), presentationData: self.presentationData, pushController: { [weak self] c in
```
Replace with:
```swift
self.displayNode = ChatRecentActionsControllerNode(context: self.context, controller: self, peer: self.peer, presentationData: self.presentationData, pushController: { [weak self] c in
```
`ChatRecentActionsController.peer` is already declared `EnginePeer` at line 42 (`public init(context: AccountContext, peer: EnginePeer, ...)`) — the type carries through to the now-`EnginePeer`-typed init parameter.
---
## Task 3: Full-project Bazel build
**Files:** none (verification only).
- [ ] **Step 1: Run the build**
Run:
```sh
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent \
--buildNumber=1 --configuration=debug_sim_arm64
```
Expected: clean build (`bazel build complete` or equivalent green output). No `--continueOnError` because the small scope makes the first error informative.
Build cost projection: consumer-only, ~25s. If it exceeds ~60s, suspect a cascade leak.
- [ ] **Step 2: If build fails, triage iteration**
If errors land in `ChatRecentActionsControllerNode.swift` or `ChatRecentActionsController.swift`:
- Read the failing line.
- Common failure modes from prior waves:
- **Always-false `is` warning under `-warnings-as-errors`:** none expected here (pre-flight grep confirmed no `is TelegramChannel` checks on `self.peer`). If one surfaces anyway, convert to `case .channel = self.peer`.
- **Always-failing `as?` cast warning:** leftover `as? TelegramX` not converted in step 4/5/6. Re-grep `(self|strongSelf)\.peer as\?` over the file.
- **Type mismatch on closure-capture alias:** none expected here (pre-flight grep confirmed only `strongSelf.peer` and `self.peer` aliases, both ride the type change).
- **Type mismatch on `.id` access:** would indicate a regression in the `EnginePeer.Id` typealias — STOP and re-read CLAUDE.md, this is not a wave-103 issue.
- **Unused-variable warning under `-warnings-as-errors`:** a `case let .channel(peer)` binding not used inside the body. Re-read step 4/5/6 — if the inner block never references the bound name, switch to `case .channel = ...` and remove the binding.
Fix in place and re-run step 1. Budget: 2 iterations.
If errors land outside those 2 files: **STOP**. The wave was supposed to be self-contained. Re-read the spec, identify the missed call site, decide whether to add it or abandon the wave.
---
## Task 4: Post-edit residue grep
**Files:** none (verification only).
- [ ] **Step 1: Cast residue grep**
Run:
```sh
grep -nE "(self|strongSelf)\.peer as\? Telegram(Channel|Group|User)" \
submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/
```
Expected: empty output.
- [ ] **Step 2: Boundary `_asPeer()` residue grep**
Run:
```sh
grep -nE "self\.peer\._asPeer\(\)" \
submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/
```
Expected: empty output.
- [ ] **Step 3: `import Postbox` residue grep**
Run:
```sh
grep -rn "^import Postbox$" \
submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/
```
Expected: empty output. The module is now Postbox-import-free.
- [ ] **Step 4: Sanity check — `peer: Peer` annotations**
Run:
```sh
grep -nE "peer: Peer\b" \
submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsControllerNode.swift
```
Expected: empty output. (The 3 `as? TelegramChannel` downcasts on `self.peer` were the only sources; both `peer: Peer` annotations on stored field and init param are now `peer: EnginePeer`.)
---
## Task 5: Commit the wave
**Files:** none (git only).
- [ ] **Step 1: Stage the 2 modified files**
```sh
git add \
submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsControllerNode.swift \
submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsController.swift
```
- [ ] **Step 2: Confirm staging is clean**
```sh
git status --short | grep -v "^??"
```
Expected output: only the 2 staged files (lines starting with `M `). If other modified files appear, they predate the wave (per CLAUDE.md memory: `build-system/bazel-rules/sourcekit-bazel-bsp` submodule marker is pre-existing WIP).
- [ ] **Step 3: Commit**
```sh
git commit -m "$(cat <<'EOF'
Postbox -> TelegramEngine wave 103
Migrate ChatRecentActionsControllerNode.peer Peer -> EnginePeer.
Closes the wave-71 shadow: caller already held EnginePeer and demoted
at the boundary. 7 edits / 2 files.
Drops 1 boundary _asPeer() at ChatRecentActionsController:277, drops
import Postbox at ChatRecentActionsControllerNode:5, rewrites 3
`as? TelegramChannel` downcasts to `case let .channel(...)` (wave-41/45
idiom).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 4: Verify commit**
```sh
git log --oneline -1
```
Expected: shows the wave 103 commit as HEAD.
---
## Task 6: Update outcome log + memory
**Files:**
- Modify: `docs/superpowers/postbox-refactor-log.md`
- Modify: `~/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/project_postbox_refactor_next_wave.md`
- Modify: `~/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/MEMORY.md`
- [ ] **Step 1: Append wave 103 outcome to refactor log**
Append a "Wave 103 outcome" entry at the chronological end of `docs/superpowers/postbox-refactor-log.md`. Use the most recent wave-outcome entry as a structural template. Include:
- Commit hash (from Task 5 step 4).
- Iteration count (1 if first-pass-clean; 2 if Task 3 step 2 fired).
- Net-bridge accounting: −1 boundary `_asPeer()` (CRAC:277), −1 `import Postbox` (CRACN:5). 0 ADD wraps. 3 cast → case-let conversions (CRACN:899/948/1088).
- Bazel build duration (from Task 3 step 1 output).
- Wave-shape note: wave-71-shadow close, single-iter target validated.
- [ ] **Step 2: Update next-wave memory**
Edit `~/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/project_postbox_refactor_next_wave.md`:
- Add the wave 103 outcome line into the recent-waves section (commit hash + 7-edit / 2-file / 1-iter summary).
- Remove the now-stale `ChatRecentActionsControllerNode.peer: Peer -> EnginePeer` candidate line (currently bullet 5 in the candidates list).
- Update the top frontmatter `description` to reflect wave 103 landed and propose wave 104.
- Promote the next candidate (likely one of: `cachedResourceRepresentation` foundational facade, `RenderedPeer` cascade kickoff, `SelectivePrivacyPeer` foundational, or another Shape-C/D mini-refactor) to the top of the candidates list.
- [ ] **Step 3: Update MEMORY.md index**
Edit `~/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/MEMORY.md`:
- Update the `[Postbox refactor next wave]` line to mention wave 103 landed and shift the "Wave 103+ Shape-C/D candidates" framing forward to "Wave 104+ candidates".
- [ ] **Step 4: Commit the doc update**
```sh
git add docs/superpowers/postbox-refactor-log.md
git commit -m "$(cat <<'EOF'
docs: log wave 103 outcome
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
(Memory file updates at `~/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/` are not committed — they live outside the repo.)
---
## Net delta projection (from spec)
| Category | Count | Sites |
|---|---|---|
| Internal bridge drops | −1 | CRAC:277 (`_asPeer()`) |
| `import Postbox` drops | −1 | CRACN:5 |
| ADD wraps | 0 | no Peer-only property accesses on bare `self.peer` |
| Cast → case-let conversions | 3 | CRACN:899, CRACN:948, CRACN:1088 |
| Type annotations updated | 2 | CRACN:46 (stored field), CRACN:111 (init param) |
| Postbox-free module count | +1 | `Components/Chat/ChatRecentActionsController/` joins the list |
**Total commit footprint:** 7 line edits across 2 files, plus a docs commit for the outcome log.

260
docs/superpowers/plans/2026-04-26-postbox-wave-103-retry-account-manager-store-resource-data-drain.md
View file

@ -1,260 +0,0 @@
# Wave 103 (retry): accountManager.mediaBox.storeResourceData drain Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Drain 5 remaining `accountManager.mediaBox.storeResourceData(...)` Shape-A sites against the wave-94 `AccountManagerResources.storeResourceData(id:data:synchronous:)` facade. Wave 103 (retry) of the Postbox → TelegramEngine refactor, after the abandonment of the original wave-103 plan.
**Architecture:** Wave-shape-G drain. Pure call-site rewrite; no facade addition, no TelegramCore touch, no public-API change. 5 sites across 2 consumer files (`ThemeUpdateManager.swift`, `WallpaperResources.swift`) migrated via 3 `Edit` calls (1 single + 2 `replace_all=true` batches).
**Tech Stack:** Swift, Bazel via `Make.py`, no unit tests (per `CLAUDE.md`). Verification is the full-project debug-sim-arm64 build.
**Iteration budget:** 1 (target first-pass-clean given mechanical scope and validated facade).
**Note on TDD:** This project has no unit tests. Each task writes the edits, then verifies via Bazel build + residue grep.
---
## File Structure
| File | Role | Changes |
|---|---|---|
| `submodules/TelegramUI/Sources/ThemeUpdateManager.swift` | Theme-update background sync | 1 site migrated |
| `submodules/WallpaperResources/Sources/WallpaperResources.swift` | Wallpaper resource pipeline | 4 sites migrated via 2 `replace_all=true` batches |
No public-API ripple — both files are leaf consumers of the wave-94 facade.
---
## Task 1: ThemeUpdateManager.swift — single-site migration
**Files:**
- Modify: `submodules/TelegramUI/Sources/ThemeUpdateManager.swift`
**Edits in this task:** 1.
- [ ] **Step 1: Migrate the storeResourceData call at line 112**
Find:
```swift
accountManager.mediaBox.storeResourceData(file.file.resource.id, data: fullSizeData, synchronous: true)
```
Replace with:
```swift
accountManager.resources.storeResourceData(id: EngineMediaResource.Id(file.file.resource.id), data: fullSizeData, synchronous: true)
```
`accountManager` here is closure-captured from `presentationThemeSettingsUpdated(_:)` scope, typed `AccountManager<TelegramAccountManagerTypes>`. The facade is exposed via `public extension AccountManager { var resources: AccountManagerResources }`.
---
## Task 2: WallpaperResources.swift — two batched migrations
**Files:**
- Modify: `submodules/WallpaperResources/Sources/WallpaperResources.swift`
**Edits in this task:** 2 (each `replace_all=true`, covering 2 sites apiece).
- [ ] **Step 1: Migrate the `reference.resource.id` pattern (lines 973, 1214)**
Use `Edit` with `replace_all=true`:
Find:
```swift
accountManager.mediaBox.storeResourceData(reference.resource.id, data: data)
```
Replace with:
```swift
accountManager.resources.storeResourceData(id: EngineMediaResource.Id(reference.resource.id), data: data)
```
Both sites share identical text (verified by pre-flight grep). `replace_all=true` handles both atomically.
- [ ] **Step 2: Migrate the `file.file.resource.id` pattern (lines 1260, 1523)**
Use `Edit` with `replace_all=true`:
Find:
```swift
accountManager.mediaBox.storeResourceData(file.file.resource.id, data: fullSizeData)
```
Replace with:
```swift
accountManager.resources.storeResourceData(id: EngineMediaResource.Id(file.file.resource.id), data: fullSizeData)
```
Both sites share identical text. `replace_all=true` handles both atomically.
---
## Task 3: Full-project Bazel build
**Files:** none (verification only).
- [ ] **Step 1: Run the build**
```sh
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent \
--buildNumber=1 --configuration=debug_sim_arm64
```
Expected: clean build (`bazel build complete` / `INFO: Build completed successfully`). No `--continueOnError` because the small scope makes the first error informative.
Build cost projection: WallpaperResources is foundational with wide rebuild fan-out; expect ~30-90s.
- [ ] **Step 2: If build fails, triage iteration**
Common failure modes:
- **`EngineMediaResource.Id` not in scope** — verify `import TelegramCore` is at the top of the failing file (it should be — pre-flight inventoried both files have it). If absent, add it.
- **Type mismatch on `id:` parameter** — would suggest an unexpected `MediaResourceId` subtype. STOP and re-read; the migration assumed `MediaResource.id: MediaResourceId` for both `reference.resource` and `file.file.resource`. Both should resolve to `MediaResourceId` per Postbox protocol.
- **`accountManager.resources` not in scope** — the `public extension AccountManager` exists in TelegramCore (wave 94). If unreachable, the consumer's BUILD might be missing a TelegramCore dep — but both files already use TelegramCore types, so this should not happen. STOP if it does.
If errors land outside those 2 files: **STOP and report BLOCKED**. The wave is supposed to be self-contained.
Fix in place and re-run step 1. Budget: 2 iterations.
---
## Task 4: Post-edit residue grep
**Files:** none (verification only).
- [ ] **Step 1: Verify zero remaining `accountManager.mediaBox.storeResourceData` in the 2 touched files**
Run:
```sh
grep -rn "accountManager\.mediaBox\.storeResourceData" \
submodules/TelegramUI/Sources/ThemeUpdateManager.swift \
submodules/WallpaperResources/Sources/WallpaperResources.swift
```
Expected: empty output.
---
## Task 5: Commit the wave
**Files:** none (git only).
- [ ] **Step 1: Stage the 2 modified files**
```sh
git add \
submodules/TelegramUI/Sources/ThemeUpdateManager.swift \
submodules/WallpaperResources/Sources/WallpaperResources.swift
```
- [ ] **Step 2: Confirm staging is clean**
```sh
git status --short | grep -v "^??"
```
Expected output: only the 2 staged files (lines starting with `M `). The line `m build-system/bazel-rules/sourcekit-bazel-bsp` is pre-existing WIP and should NOT appear in the staged list.
- [ ] **Step 3: Commit**
```sh
git commit -m "$(cat <<'EOF'
Postbox -> TelegramEngine wave 103 (retry)
Drain 5 accountManager.mediaBox.storeResourceData(...) Shape-A sites
that the wave-94/95-99 sweep missed. All 5 migrated to
accountManager.resources.storeResourceData(id: EngineMediaResource.Id(...))
against the existing wave-94 facade.
Sites: ThemeUpdateManager:112 (with synchronous: true),
WallpaperResources:973, 1214 (reference.resource.id pattern, replace_all),
WallpaperResources:1260, 1523 (file.file.resource.id pattern, replace_all).
5 sites / 2 files / 3 Edit calls. Consumer-only build.
Wave-103 retry after the abandonment of ChatRecentActionsControllerNode
peer migration; see postbox-refactor-log "Wave 103 outcome" for the
forensics.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 4: Verify commit**
```sh
git log --oneline -1
```
Expected: shows the wave 103 (retry) commit as HEAD.
---
## Task 6: Update outcome log + memory
**Files:**
- Modify: `docs/superpowers/postbox-refactor-log.md`
- Modify: `~/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/project_postbox_refactor_next_wave.md`
- Modify: `~/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/MEMORY.md`
- [ ] **Step 1: Append wave 103 (retry) outcome to refactor log**
Append a "Wave 103 (retry) outcome" entry to `docs/superpowers/postbox-refactor-log.md`. Include:
- Commit hash (from Task 5 step 4).
- Iteration count (1 if first-pass-clean; 2 if Task 3 step 2 fired).
- Bazel build duration.
- Net-delta accounting: −5 raw `mediaBox.X` accesses, +5 facade calls, +5 `EngineMediaResource.Id(...)` wraps (canonical engine-side, not Postbox bridges).
- Wave-shape note: G drain, validates the wave-94 facade across an additional 2-module footprint.
- [ ] **Step 2: Update next-wave memory**
Edit `project_postbox_refactor_next_wave.md`:
- Add wave 103 (retry) outcome line into the recent-waves section.
- Mark the 5 sites as drained; remove from candidate inventories (the file currently lists "Wave 95+ candidates" with stale storeResourceData entries — clean those up).
- Update the top frontmatter `description` to reflect wave 103 (retry) landed.
- Promote next candidate. Options: 7-site `resourceData(...)` drain (would need a new facade method or use existing `data(resource:)`), DirectMediaImageCache Shape-C/D, or pivot to a foundational wave.
- [ ] **Step 3: Update MEMORY.md index**
Edit `~/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/MEMORY.md`:
- Update the `[Postbox refactor next wave]` line to mention wave 103 (retry) landed.
- [ ] **Step 4: Commit the doc update**
```sh
git add docs/superpowers/postbox-refactor-log.md
git commit -m "$(cat <<'EOF'
docs: log wave 103 (retry) outcome
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
(Memory file updates are not committed — they live outside the repo.)
---
## Net delta projection
| Category | Count | Sites |
|---|---|---|
| Raw `mediaBox.X` access drops | −5 | TUM:112 + WR:973, 1214, 1260, 1523 |
| Facade calls added | +5 | same sites, migrated form |
| `EngineMediaResource.Id(...)` wraps | +5 | canonical engine-side constructs (not Postbox bridges) |
| `import Postbox` drops | 0 | both files retain Postbox import for unrelated symbols |
| Postbox-free module count | 0 | no module dropped from the import list |
**Total commit footprint:** 5 line edits (3 Edit calls) across 2 files, plus a docs commit for the outcome log.

331
docs/superpowers/plans/2026-04-26-postbox-wave-104-account-manager-resource-data-drain-3-sites.md
View file

@ -1,331 +0,0 @@
# Wave 104: accountManager.mediaBox.resourceData drain (3 clean sites) Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Drain 3 of 8 `accountManager.mediaBox.resourceData(...)` Shape-A sites against the existing wave-32 / wave-94 `AccountManagerResources.data(resource:)` facade. Wave 104 of the Postbox → TelegramEngine refactor.
**Architecture:** Wave-shape-G drain with a documented consumer field rename. Single-file consumer migration in `submodules/WallpaperResources/Sources/WallpaperResources.swift`. 3 call rewrites + 3 consumer-side `.complete` → `.isComplete` renames, 6 Edit calls total. The remaining 5 of the original 8 `resourceData` candidates are deferred (2 cross a `MediaResourceData` flow-out cascade, 3 are coupled to postbox-side via `combineLatest` typed tuples).
**Tech Stack:** Swift, Bazel via `Make.py`, no unit tests. Verification is the full-project debug-sim-arm64 build.
**Iteration budget:** 1 (target first-pass-clean given verified pre-flight inventory).
**Note on TDD:** This project has no unit tests. Each task writes the edits, then verifies via Bazel build + residue grep.
---
## File Structure
| File | Role | Changes |
|---|---|---|
| `submodules/WallpaperResources/Sources/WallpaperResources.swift` | Wallpaper resource pipeline | 3 call rewrites + 3 consumer renames |
No public-API ripple — leaf-consumer migration against an existing facade.
---
## Task 1: WallpaperResources.swift — call rewrites (3 edits)
**Files:**
- Modify: `submodules/WallpaperResources/Sources/WallpaperResources.swift`
**Edits in this task:** 3.
- [ ] **Step 1: Migrate the call at line 957 (`reference.resource` argument)**
Find:
```swift
let maybeFetched = accountManager.mediaBox.resourceData(reference.resource, option: .complete(waitUntilFetchStatus: false), attemptSynchronously: synchronousLoad)
```
Replace with:
```swift
let maybeFetched = accountManager.resources.data(resource: EngineMediaResource(reference.resource), attemptSynchronously: synchronousLoad)
```
Note: `waitUntilFetchStatus: false` is omitted because the facade default is `false`. The site explicitly passed `false`, so behavior is preserved.
- [ ] **Step 2: Migrate the call at line 1164 (`fileReference.media.resource` argument)**
Find:
```swift
let maybeFetched = accountManager.mediaBox.resourceData(fileReference.media.resource, option: .complete(waitUntilFetchStatus: false), attemptSynchronously: synchronousLoad)
```
Replace with:
```swift
let maybeFetched = accountManager.resources.data(resource: EngineMediaResource(fileReference.media.resource), attemptSynchronously: synchronousLoad)
```
Same `waitUntilFetchStatus: false` omission rationale.
- [ ] **Step 3: Migrate the call at line 1264 (`file.file.resource` argument, no option)**
Find:
```swift
return accountManager.mediaBox.resourceData(file.file.resource)
```
Replace with:
```swift
return accountManager.resources.data(resource: EngineMediaResource(file.file.resource))
```
The original used the underlying `MediaBox.resourceData(_ resource:)` overload's defaults — facade defaults match exactly (`pathExtension: nil`, `waitUntilFetchStatus: false`, `attemptSynchronously: false`).
---
## Task 2: WallpaperResources.swift — consumer-side `.complete` → `.isComplete` renames (3 edits)
**Files:**
- Modify: `submodules/WallpaperResources/Sources/WallpaperResources.swift`
**Edits in this task:** 3.
`EngineMediaResource.ResourceData` exposes `.isComplete` (renamed from `MediaResourceData.complete`). All three migrated call sites have a single consumer-side `.complete` access on the migrated result that needs renaming.
- [ ] **Step 1: Rename `maybeData.complete` at line 961 (consumer of site 957)**
Find:
```swift
if maybeData.complete {
```
Replace with:
```swift
if maybeData.isComplete {
```
The leading whitespace (8 spaces) must match exactly.
- [ ] **Step 2: Rename `maybeData.complete` at line 1168 (consumer of site 1164)**
Find:
```swift
if maybeData.complete && isSupportedTheme {
```
Replace with:
```swift
if maybeData.isComplete && isSupportedTheme {
```
The leading whitespace (16 spaces) must match exactly.
- [ ] **Step 3: Rename `data.complete` at line 1266 (consumer of site 1264)**
Find:
```swift
if data.complete, let imageData = try? Data(contentsOf: URL(fileURLWithPath: data.path)) {
```
Replace with:
```swift
if data.isComplete, let imageData = try? Data(contentsOf: URL(fileURLWithPath: data.path)) {
```
The leading whitespace (36 spaces) must match exactly.
The `data.path` access on the same line is unchanged — both `MediaResourceData.path` and `EngineMediaResource.ResourceData.path` are `String`.
---
## Sites NOT touched (deferred)
For the implementer's awareness — these `.complete` accesses on UNRELATED bindings stay raw and are NOT to be renamed:
- `WallpaperResources.swift:968` — `return data.complete ? try? Data(contentsOf: URL(fileURLWithPath: data.path)) : nil` — this `data` is bound from `account.postbox.mediaBox.resourceData(...)` (postbox-side, not migrated). STAYS `.complete`.
- Other `.complete` accesses elsewhere in the file that aren't on the 3 migrated bindings — STAY.
The 3 renames target only the 3 specific lines listed in Task 2 steps 1-3. Do NOT use `replace_all=true` for renames — bindings differ per scope.
---
## Task 3: Full-project Bazel build
**Files:** none (verification only).
- [ ] **Step 1: Run the build**
```sh
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent \
--buildNumber=1 --configuration=debug_sim_arm64
```
Expected: clean build (`bazel build complete` / `INFO: Build completed successfully`). No `--continueOnError`. Build cost projection: ~30-60s (consumer-only, foundational module rebuild fan-out).
- [ ] **Step 2: If build fails, triage iteration**
Common failure modes:
- **`EngineMediaResource` constructor not found** — verify `import TelegramCore` at the top of WallpaperResources.swift (it should already be there). If missing, add it.
- **Type mismatch on `resource:` parameter** — would suggest the argument expression isn't `MediaResource`-typed. STOP and check the actual type at the failing site.
- **Type mismatch on `.isComplete` rename** — if the closure parameter binding is somehow inferred wrong (e.g., Swift inferred the OLD `MediaResourceData` type because the call rewrite didn't take effect), the rename will fail. Re-read the diff and verify the call rewrite landed.
- **`data.path` type mismatch** — should not happen; both types expose `path: String`. If it does, STOP and re-read.
If errors land outside WallpaperResources.swift: STOP and report BLOCKED. The wave is supposed to be self-contained.
Iteration budget: 2.
---
## Task 4: Post-edit residue grep
**Files:** none (verification only).
- [ ] **Step 1: Verify the 3 migrated call sites are gone**
Run:
```sh
grep -nE "accountManager\.mediaBox\.resourceData\(" submodules/WallpaperResources/Sources/WallpaperResources.swift
```
Expected: exactly 3 lines remaining (L33, L59, L401 — the deferred combineLatest sites). The migrated lines (originally 957, 1164, 1264) should NOT appear.
- [ ] **Step 2: Verify the 3 renames are applied**
Run:
```sh
grep -nE "maybeData\.complete\b" submodules/WallpaperResources/Sources/WallpaperResources.swift
```
Expected: empty output. Both `maybeData.complete` accesses (originally L961, L1168) should be gone.
```sh
grep -nE "if data\.complete," submodules/WallpaperResources/Sources/WallpaperResources.swift
```
Expected: no line at L1266 (the migrated site). Other `data.complete` accesses on postbox-side bindings (e.g., L968) may remain — those are out of scope.
---
## Task 5: Commit the wave
**Files:** none (git only).
- [ ] **Step 1: Stage the 1 modified file**
```sh
git add submodules/WallpaperResources/Sources/WallpaperResources.swift
```
- [ ] **Step 2: Confirm staging is clean**
```sh
git status --short | grep -v "^??"
```
Expected: only the 1 staged file (line starting with `M `). The line `m build-system/bazel-rules/sourcekit-bazel-bsp` is pre-existing WIP and should NOT appear in the staged list.
- [ ] **Step 3: Commit**
```sh
git commit -m "$(cat <<'EOF'
Postbox -> TelegramEngine wave 104
Drain 3 accountManager.mediaBox.resourceData(...) Shape-A sites against
the existing wave-32 / wave-94 AccountManagerResources.data(resource:)
facade. Sites: WallpaperResources:957 (reference.resource), :1164
(fileReference.media.resource), :1264 (file.file.resource).
Migration: accountManager.mediaBox.resourceData(X, option: .complete(
waitUntilFetchStatus: false)[, attemptSynchronously: Y]) -> accountManager
.resources.data(resource: EngineMediaResource(X)[, attemptSynchronously:
Y]). Plus 3 consumer-side .complete -> .isComplete renames at L961,
L1168, L1266 to match EngineMediaResource.ResourceData field name.
3 sites / 1 file / 6 Edit calls. Consumer-only build.
Deferred: 2 sites in FetchCachedRepresentations.swift (482, 490) flow
data: MediaResourceData into fetchCachedScaled*Representation cascade;
3 sites in WallpaperResources (33, 59, 401) coupled to postbox-side via
combineLatest typed tuples.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 4: Verify commit**
```sh
git log --oneline -1
```
Expected: shows the wave 104 commit as HEAD.
---
## Task 6: Update outcome log + memory
**Files:**
- Modify: `docs/superpowers/postbox-refactor-log.md`
- Modify: `~/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/project_postbox_refactor_next_wave.md`
- Modify: `~/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/MEMORY.md`
- [ ] **Step 1: Append wave 104 outcome to refactor log**
Append a "Wave 104 outcome" entry to `docs/superpowers/postbox-refactor-log.md` matching the format of "Wave 103 (retry) outcome". Include:
- Commit hash (from Task 5 step 4).
- Iteration count (1 if first-pass-clean; 2 if Task 3 step 2 fired).
- Bazel build duration (from Task 3 step 1 output).
- Net-delta accounting: −3 raw `mediaBox.X` accesses, +3 facade calls, +3 `EngineMediaResource(...)` wraps, +3 consumer field renames.
- Wave-shape note: G drain with documented consumer field rename. The pre-flight identified a `MediaResourceData`-typed-function-parameter barrier (`fetchCachedScaled*Representation` family) that forced 2 sites into the deferred bucket — illustrates the wave-71-shadow lesson applied to result-type cascades, not just peer migrations.
- [ ] **Step 2: Update next-wave memory**
Edit `project_postbox_refactor_next_wave.md`:
- Add wave 104 outcome line into the recent-waves section.
- Update accountManager-side facade drain status table: `resourceData` count drops from 8 → 5 (3 drained, 5 deferred).
- Add a new section (or extend an existing one) documenting the "Postbox-typed-function-parameter barrier" pattern, with `Message.peers: SimpleDictionary<PeerId, Peer>` (wave-103 lesson) and now `fetchCachedScaled*Representation(resourceData: MediaResourceData)` as the two known instances.
- [ ] **Step 3: Update MEMORY.md index**
Edit `~/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/MEMORY.md`:
- Update the `[Postbox refactor next wave]` line to mention wave 104 landed.
- [ ] **Step 4: Commit the doc update**
```sh
git add docs/superpowers/postbox-refactor-log.md
git commit -m "$(cat <<'EOF'
docs: log wave 104 outcome
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
(Memory file updates are not committed — they live outside the repo.)
---
## Net delta projection
| Category | Count | Sites |
|---|---|---|
| Raw `mediaBox.X` access drops | −3 | WR:957, 1164, 1264 |
| Facade calls added | +3 | same sites, migrated form |
| `EngineMediaResource(...)` wraps | +3 | canonical engine-side, not Postbox bridges |
| Consumer field renames | +3 | WR:961 (`maybeData.complete` → `.isComplete`), WR:1168 (same), WR:1266 (`data.complete` → `.isComplete`) |
| `import Postbox` drops | 0 | WallpaperResources retains import for unrelated symbols |
**Total commit footprint:** 6 line edits in 1 file, plus a docs commit for the outcome log.

489
docs/superpowers/plans/2026-04-26-postbox-wave-105-device-contact-info-subject-engine-peer.md
View file

@ -1,489 +0,0 @@
# Wave 105: DeviceContactInfoSubject enum payload Peer? → EnginePeer? Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task.
**Goal:** Migrate `DeviceContactInfoSubject` enum's 3 case payloads + 2 callback signatures + 1 computed property from raw Postbox `Peer?` to `EnginePeer?`. Wave 105 of the Postbox → TelegramEngine refactor.
**Architecture:** Multi-module enum-payload migration (wave-91 shape). 17 edits across 5 files. AccountContext.swift hosts the enum + property. DeviceContactInfoController.swift is the primary consumer. 4 construction sites in TelegramUI/PeerInfoUI/StoryContainerScreen/ChatController. Net wrap delta: −8 (drops 10, adds 2 at Chat-side construction barriers documented per spec).
**Tech Stack:** Swift, Bazel via `Make.py`, no unit tests. Verification is the full-project debug-sim-arm64 build.
**Iteration budget:** 1-3 (wave-91 precedent: 2 iter for similar shape).
**Note on TDD:** No unit tests in this project. Each task writes the edits, then verifies via Bazel build + residue grep.
---
## File Structure
| File | Role | Edits |
|---|---|---|
| `submodules/AccountContext/Sources/AccountContext.swift` | Enum definition + computed property | 4 type-line edits |
| `submodules/PeerInfoUI/Sources/DeviceContactInfoController.swift` | Primary consumer | 9 edits (5 `_asPeer` drops + 3 `.flatMap` simplifications + 1 downcast rewrite) |
| `submodules/TelegramUI/Sources/ChatControllerOpenAttachmentMenu.swift` | Chat-side construction (Pattern E ADD bridges) | 1 Edit (replace_all=true covers 2 sites) |
| `submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerViewSendMessage.swift` | Story-side construction | 1 edit |
| `submodules/TelegramUI/Sources/OpenChatMessage.swift` | OpenChatMessage construction | 1 edit |
---
## Task 1: AccountContext.swift — enum + computed property type changes
**File:** `submodules/AccountContext/Sources/AccountContext.swift`
- [ ] **Step 1: Migrate the 3 enum case payloads (single Edit covers consecutive lines)**
Find:
```swift
public enum DeviceContactInfoSubject {
case vcard(Peer?, DeviceContactStableId?, DeviceContactExtendedData)
case filter(peer: Peer?, contactId: DeviceContactStableId?, contactData: DeviceContactExtendedData, completion: (Peer?, DeviceContactExtendedData) -> Void)
case create(peer: Peer?, contactData: DeviceContactExtendedData, isSharing: Bool, shareViaException: Bool, completion: (Peer?, DeviceContactStableId, DeviceContactExtendedData) -> Void)
public var peer: Peer? {
```
Replace with:
```swift
public enum DeviceContactInfoSubject {
case vcard(EnginePeer?, DeviceContactStableId?, DeviceContactExtendedData)
case filter(peer: EnginePeer?, contactId: DeviceContactStableId?, contactData: DeviceContactExtendedData, completion: (EnginePeer?, DeviceContactExtendedData) -> Void)
case create(peer: EnginePeer?, contactData: DeviceContactExtendedData, isSharing: Bool, shareViaException: Bool, completion: (EnginePeer?, DeviceContactStableId, DeviceContactExtendedData) -> Void)
public var peer: EnginePeer? {
```
This single Edit covers all 4 type-line changes in `AccountContext.swift`. The `contactData: DeviceContactExtendedData` computed property (lines 719-727) is unaffected.
---
## Task 2: DeviceContactInfoController.swift — Pattern D downcast rewrite (1 edit)
**File:** `submodules/PeerInfoUI/Sources/DeviceContactInfoController.swift`
- [ ] **Step 1: Rewrite the `as? TelegramUser` downcast at line 849**
Find:
```swift
if let peer = peer as? TelegramUser {
```
Replace with:
```swift
if case let .user(peer) = peer {
```
The leading whitespace (8 spaces) must match exactly. The outer `peer: EnginePeer?` (from `case let .create(peer, ...) = subject` at L845) is shadowed inside the if-body by `peer: TelegramUser` (the `.user` case associated value). Inner body access (`peer.firstName`, `peer.lastName`, `peer.phone`) works on the rebinding.
---
## Task 3: DeviceContactInfoController.swift — Pattern C `.flatMap` simplifications (3 edits)
**File:** `submodules/PeerInfoUI/Sources/DeviceContactInfoController.swift`
- [ ] **Step 1: Simplify `.vcard` case body at line 942**
Find:
```swift
case let .vcard(peer, id, data):
contactData = .single((peer.flatMap(EnginePeer.init), id, data))
```
Replace with:
```swift
case let .vcard(peer, id, data):
contactData = .single((peer, id, data))
```
- [ ] **Step 2: Simplify `.filter` case body at line 944**
Find:
```swift
case let .filter(peer, id, data, _):
contactData = .single((peer.flatMap(EnginePeer.init), id, data))
```
Replace with:
```swift
case let .filter(peer, id, data, _):
contactData = .single((peer, id, data))
```
- [ ] **Step 3: Simplify `.create` case body at line 946**
Find:
```swift
case let .create(peer, data, share, shareViaExceptionValue, _):
contactData = .single((peer.flatMap(EnginePeer.init), nil, data))
```
Replace with:
```swift
case let .create(peer, data, share, shareViaExceptionValue, _):
contactData = .single((peer, nil, data))
```
After Task 1's enum migration, the destructured `peer: EnginePeer?` is the target type — `.flatMap(EnginePeer.init)` becomes a redundant round-trip.
---
## Task 4: DeviceContactInfoController.swift — Pattern B `_asPeer` drops at completion calls (2 edits)
**File:** `submodules/PeerInfoUI/Sources/DeviceContactInfoController.swift`
- [ ] **Step 1: Drop `_asPeer()` at completion call line 1105**
Find:
```swift
completion(peerAndContactData.0?._asPeer(), filteredData)
```
Replace with:
```swift
completion(peerAndContactData.0, filteredData)
```
`peerAndContactData.0` is `EnginePeer?` from the typed signal at L939. Completion's first parameter type changes from `Peer?` to `EnginePeer?` per Task 1.
- [ ] **Step 2: Drop `_asPeer()` at completion call line 1224**
Find:
```swift
completion(contactIdAndData.2?._asPeer(), contactIdAndData.0, contactIdAndData.1)
```
Replace with:
```swift
completion(contactIdAndData.2, contactIdAndData.0, contactIdAndData.1)
```
`contactIdAndData.2` is `EnginePeer?` per the typed signal `(DeviceContactStableId, DeviceContactExtendedData, EnginePeer?)?` declared at L1175.
---
## Task 5: DeviceContactInfoController.swift — Pattern A `_asPeer` drops at construction (3 edits)
**File:** `submodules/PeerInfoUI/Sources/DeviceContactInfoController.swift`
- [ ] **Step 1: Drop `_asPeer()` at line 1289**
Find:
```swift
replaceControllerImpl?(deviceContactInfoController(context: context, environment: environment, subject: .vcard(peer?._asPeer(), contactId, contactData), completed: nil, cancelled: nil))
```
Replace with:
```swift
replaceControllerImpl?(deviceContactInfoController(context: context, environment: environment, subject: .vcard(peer, contactId, contactData), completed: nil, cancelled: nil))
```
- [ ] **Step 2: Drop `_asPeer()` at line 1443**
Find:
```swift
parentController.present(deviceContactInfoController(context: ShareControllerAppAccountContext(context: context), environment: ShareControllerAppEnvironment(sharedContext: context.sharedContext), subject: .create(peer: peer?._asPeer(), contactData: contactData, isSharing: false, shareViaException: false, completion: { peer, stableId, contactData in
```
Replace with:
```swift
parentController.present(deviceContactInfoController(context: ShareControllerAppAccountContext(context: context), environment: ShareControllerAppEnvironment(sharedContext: context.sharedContext), subject: .create(peer: peer, contactData: contactData, isSharing: false, shareViaException: false, completion: { peer, stableId, contactData in
```
- [ ] **Step 3: Drop `_asPeer()` at line 1489**
Find:
```swift
controller?.present(context.sharedContext.makeDeviceContactInfoController(context: ShareControllerAppAccountContext(context: context), environment: ShareControllerAppEnvironment(sharedContext: context.sharedContext), subject: .create(peer: peer?._asPeer(), contactData: contactData, isSharing: peer != nil, shareViaException: false, completion: { _, _, _ in
```
Replace with:
```swift
controller?.present(context.sharedContext.makeDeviceContactInfoController(context: ShareControllerAppAccountContext(context: context), environment: ShareControllerAppEnvironment(sharedContext: context.sharedContext), subject: .create(peer: peer, contactData: contactData, isSharing: peer != nil, shareViaException: false, completion: { _, _, _ in
```
All 3 sites have `peer` source already typed as `EnginePeer?` per inventory.
---
## Task 6: ChatControllerOpenAttachmentMenu.swift — Pattern E ADD wraps (1 Edit, 2 sites via replace_all=true)
**File:** `submodules/TelegramUI/Sources/ChatControllerOpenAttachmentMenu.swift`
- [ ] **Step 1: Add `.flatMap(EnginePeer.init)` wrap at lines 683 and 1850**
Use Edit with `replace_all=true`. Find:
```swift
subject: .filter(peer: peerAndContactData.0, contactId: nil, contactData: contactData, completion: { peer, contactData in
```
Replace with:
```swift
subject: .filter(peer: peerAndContactData.0.flatMap(EnginePeer.init), contactId: nil, contactData: contactData, completion: { peer, contactData in
```
`replace_all=true` is required — both sites at L683 and L1850 share identical text. The upstream signal type is `(Peer?, DeviceContactExtendedData?)` (verified at L634 and L1822); `.flatMap(EnginePeer.init)` wraps `Peer?` to `EnginePeer?` to satisfy the migrated `.filter(peer: EnginePeer?, ...)` signature.
---
## Task 7: StoryItemSetContainerViewSendMessage.swift — Pattern A `_asPeer` drop (1 edit)
**File:** `submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerViewSendMessage.swift`
- [ ] **Step 1: Drop `_asPeer()` at line 2132**
Find:
```swift
let contactController = component.context.sharedContext.makeDeviceContactInfoController(context: ShareControllerAppAccountContext(context: component.context), environment: ShareControllerAppEnvironment(sharedContext: component.context.sharedContext), subject: .filter(peer: peerAndContactData.0?._asPeer(), contactId: nil, contactData: contactData, completion: { [weak self, weak view] peer, contactData in
```
Replace with:
```swift
let contactController = component.context.sharedContext.makeDeviceContactInfoController(context: ShareControllerAppAccountContext(context: component.context), environment: ShareControllerAppEnvironment(sharedContext: component.context.sharedContext), subject: .filter(peer: peerAndContactData.0, contactId: nil, contactData: contactData, completion: { [weak self, weak view] peer, contactData in
```
`peerAndContactData.0` is `EnginePeer?` from the typed signal at this site (the presence of `?._asPeer()` confirms it).
---
## Task 8: OpenChatMessage.swift — Pattern A `_asPeer` drop (1 edit)
**File:** `submodules/TelegramUI/Sources/OpenChatMessage.swift`
- [ ] **Step 1: Drop `_asPeer()` at line 443**
Find:
```swift
let controller = deviceContactInfoController(context: ShareControllerAppAccountContext(context: params.context), environment: ShareControllerAppEnvironment(sharedContext: params.context.sharedContext), updatedPresentationData: params.updatedPresentationData, subject: .vcard(peer?._asPeer(), nil, contactData), completed: nil, cancelled: nil)
```
Replace with:
```swift
let controller = deviceContactInfoController(context: ShareControllerAppAccountContext(context: params.context), environment: ShareControllerAppEnvironment(sharedContext: params.context.sharedContext), updatedPresentationData: params.updatedPresentationData, subject: .vcard(peer, nil, contactData), completed: nil, cancelled: nil)
```
`peer` source is already `EnginePeer?` (the `?._asPeer()` confirms the source type).
---
## Task 9: Full-project Bazel build
**Files:** none (verification only).
- [ ] **Step 1: Run the build with `--continueOnError`**
```sh
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent \
--buildNumber=1 --configuration=debug_sim_arm64 --continueOnError
```
`--continueOnError` enabled — multi-module wave; surface all errors at once if iter-1 fails.
Expected: clean build. AccountContext is foundational; expect 60-180s build cost.
- [ ] **Step 2: If build fails, triage iteration**
Common failure modes (per wave-91 precedent):
- **Type mismatch on a destructured `peer`** — a destructure body may use `peer.X` where `X` is a Peer-protocol-only method not on EnginePeer. Pre-flight inventory found ZERO such sites, but verify the failing line.
- **`.id` access on EnginePeer? doesn't compile** — would indicate an EnginePeer.Id typealias regression (very unlikely; would have failed all prior waves).
- **`case let .user(peer) = peer` doesn't compile** — verify the outer `peer` is `EnginePeer?` (after migration) and not still `Peer?`.
- **A construction site missed an `_asPeer()` drop** — re-grep `_asPeer\(\)` over the 5 touched files.
- **Hidden `Peer?`-typed completion call site** — would indicate an unmigrated callback consumer. Re-grep across consumer module sources.
If errors land outside the 5 touched files: STOP and report BLOCKED — the wave is supposed to be self-contained.
Iteration budget: 3.
---
## Task 10: Post-edit residue grep
**Files:** none (verification only).
- [ ] **Step 1: Construction-site `_asPeer` residue (expected empty)**
```sh
grep -nE "subject:\s*\.(vcard|filter|create)\(.*_asPeer\(\)" \
submodules/PeerInfoUI/Sources/DeviceContactInfoController.swift \
submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerViewSendMessage.swift \
submodules/TelegramUI/Sources/OpenChatMessage.swift
```
- [ ] **Step 2: Completion `_asPeer` residue (expected empty)**
```sh
grep -nE "completion\(.*_asPeer\(\)" submodules/PeerInfoUI/Sources/DeviceContactInfoController.swift
```
- [ ] **Step 3: `.flatMap(EnginePeer.init)` simplification residue (expected empty)**
```sh
grep -nE "peer\.flatMap\(EnginePeer\.init\)" submodules/PeerInfoUI/Sources/DeviceContactInfoController.swift
```
- [ ] **Step 4: Downcast residue (expected empty)**
```sh
grep -nE "peer as\? TelegramUser" submodules/PeerInfoUI/Sources/DeviceContactInfoController.swift
```
- [ ] **Step 5: ADD wraps applied (expected 2 lines)**
```sh
grep -nE "peerAndContactData\.0\.flatMap\(EnginePeer\.init\)" submodules/TelegramUI/Sources/ChatControllerOpenAttachmentMenu.swift
```
Expected: 2 lines (originally L683 and L1850, line numbers may have shifted slightly).
---
## Task 11: Commit the wave
**Files:** none (git only).
- [ ] **Step 1: Stage the 5 modified files**
```sh
git add \
submodules/AccountContext/Sources/AccountContext.swift \
submodules/PeerInfoUI/Sources/DeviceContactInfoController.swift \
submodules/TelegramUI/Sources/ChatControllerOpenAttachmentMenu.swift \
submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerViewSendMessage.swift \
submodules/TelegramUI/Sources/OpenChatMessage.swift
```
- [ ] **Step 2: Confirm staging**
```sh
git status --short | grep -v "^??"
```
Expected: 5 staged files (lines starting with `M `). The pre-existing `m build-system/bazel-rules/sourcekit-bazel-bsp` WIP marker should NOT appear in staged.
- [ ] **Step 3: Commit**
```sh
git commit -m "$(cat <<'EOF'
Postbox -> TelegramEngine wave 105
Migrate DeviceContactInfoSubject enum 3 case Peer? payloads + 2 callback
(Peer?, ...) -> Void signatures + 1 computed peer: Peer? property to
EnginePeer?. Wave-91-pattern multi-module enum-payload migration.
Drops 10 wraps:
- 5 _asPeer() at construction sites: DeviceContactInfoController:1289,
1443, 1489 + StoryItemSetContainerViewSendMessage:2132 +
OpenChatMessage:443.
- 2 _asPeer() at completion-call sites:
DeviceContactInfoController:1105, 1224.
- 3 .flatMap(EnginePeer.init) simplifications at
DeviceContactInfoController:942, 944, 946.
Adds 2 ADD bridges: ChatControllerOpenAttachmentMenu:683, 1850 — both
construct .filter(peer:) from peerAndContactData.0 typed (Peer?, ...);
.flatMap(EnginePeer.init) wraps to EnginePeer?. Net wrap delta: -8.
Plus 1 downcast rewrite: DeviceContactInfoController:849 — `if let peer
= peer as? TelegramUser` to `if case let .user(peer) = peer`.
5 files / 17 edits.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
- [ ] **Step 4: Verify commit**
```sh
git log --oneline -1
```
---
## Task 12: Update outcome log + memory
**Files:**
- Modify: `docs/superpowers/postbox-refactor-log.md`
- Modify: `~/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/project_postbox_refactor_next_wave.md`
- Modify: `~/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/MEMORY.md`
- [ ] **Step 1: Append wave 105 outcome to refactor log**
Include:
- Commit hash (from Task 11 step 4).
- Iteration count (1 if first-pass-clean; 2-3 if Task 9 step 2 fired).
- Bazel build duration.
- Net-delta accounting: −10 wrap drops, +2 ADD wraps, +1 downcast rewrite. Net −8 wraps.
- Wave-shape note: wave-91-pattern multi-module enum-payload migration with full pre-flight inventory clearing layers 1-4 of the wave-71-shadow checklist. Documents the value of thorough pre-flight inventory: 17 mechanical edits with 0 surprises.
- [ ] **Step 2: Update next-wave memory**
Edit `project_postbox_refactor_next_wave.md`:
- Add wave 105 outcome line into the recent-waves section.
- Mark `DeviceContactInfoSubject` candidate as drained (currently bullet 9 in deferred list).
- Promote next candidate.
- [ ] **Step 3: Update MEMORY.md index**
Update the `[Postbox refactor next wave]` line.
- [ ] **Step 4: Commit the doc update**
```sh
git add docs/superpowers/postbox-refactor-log.md
git commit -m "$(cat <<'EOF'
docs: log wave 105 outcome
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
(Memory file updates not committed — they live outside the repo.)
---
## Net delta projection
| Category | Count | Sites |
|---|---|---|
| `_asPeer()` drops at construction | −5 | DCIC:1289, 1443, 1489 + SISCVSM:2132 + OCM:443 |
| `_asPeer()` drops at completion calls | −2 | DCIC:1105, 1224 |
| `.flatMap(EnginePeer.init)` simplifications | −3 | DCIC:942, 944, 946 |
| `.flatMap(EnginePeer.init)` ADD wraps | +2 | CCOAM:683, 1850 |
| Downcast → case-let | +1 | DCIC:849 |
| Type annotations migrated | 4 | AccountContext: 3 enum cases + 1 computed property |
**Total commit footprint:** 17 line edits across 5 files, plus a docs commit for the outcome log.
**Net wrap delta:** **−8** (the wave's headline metric).

493
docs/superpowers/plans/2026-04-26-postbox-wave-106-import-drop-sweep.md
View file

@ -1,493 +0,0 @@
# Wave 106: Speculative `import Postbox` Drop Sweep (round 2) Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Drop `import Postbox` from any consumer-module Swift file in `submodules/` whose remaining content no longer references a Postbox-only symbol. Wave 106 of the Postbox → TelegramEngine refactor — round 2 of the wave-93 speculative-drop sweep.
**Architecture:** Procedural sweep with build-feedback loop. (1) inventory candidates → (2) pre-flight regex pre-restore → (3) drop imports en masse → (4) build with `--continueOnError` → (5) restore failures → iterate → (6) final clean build → (7) optional BUILD-dep sweep → (8) single atomic commit. No code semantic changes — only `import` and BUILD `deps` lines.
**Tech Stack:** Swift, Bazel via `Make.py`, `grep`/`sed` for inventory, no unit tests. Verification is the full-project debug-sim-arm64 build.
**Iteration budget:** 2-5 build cycles (wave-93 precedent: 2 iter — drop, restore, clean).
**Note on TDD:** No unit tests in this project. Each task verifies via Bazel build + diff inspection. Build feedback IS the test.
**Spec:** `docs/superpowers/specs/2026-04-26-postbox-wave-106-import-drop-sweep-design.md`.
---
## File Structure
| Artifact | Role |
|---|---|
| `/tmp/wave106-candidates.txt` | All consumer files currently `import Postbox` |
| `/tmp/wave106-skiplist.txt` | Files that match preemptive-restore regex (keep import) |
| `/tmp/wave106-droplist.txt` | candidates − skiplist; files to edit |
| `/tmp/wave106-build-iterN.log` | Per-iteration build log |
| `/tmp/wave106-restore-iterN.txt` | Files needing restore after iter N |
| `/tmp/wave106-final-droplist.txt` | Net dropped files after all iterations |
| `submodules/**/*.swift` | Edited files (single-line Edit each) |
| `submodules/**/BUILD` | (Optional Step 7) packages with no remaining Postbox imports |
---
## Task 1: Pre-flight WIP check
**File:** none (read-only).
- [ ] **Step 1: Verify clean working tree (modulo known-persistent state)**
Run:
```sh
git status --short
```
Expected output:
```
m build-system/bazel-rules/sourcekit-bazel-bsp
?? build-system/tulsi/
?? submodules/TgVoip/
?? third-party/libx264/
```
If output contains anything else (modified `M` files, other untracked dirs), HALT — there is unrelated WIP that would get tangled with the wave commit. Resolve before proceeding.
- [ ] **Step 2: Confirm we are on `master`**
Run:
```sh
git branch --show-current
```
Expected: `master`. If not, stop and ask.
---
## Task 2: Inventory candidate files
**File:** none (read-only).
- [ ] **Step 1: Build the candidate list**
Run:
```sh
grep -rl "^import Postbox" submodules --include="*.swift" \
| grep -v "^submodules/Postbox/" \
| grep -v "^submodules/TelegramCore/" \
| grep -v "^submodules/TelegramApi/" \
| sort -u > /tmp/wave106-candidates.txt
wc -l /tmp/wave106-candidates.txt
```
Expected: between ~700 and ~1200 files (wave-93-era was ~1200; waves 94-105 may have peeled some).
- [ ] **Step 2: Sanity-check the exclusion filters worked**
Run:
```sh
grep -E "^submodules/(Postbox|TelegramCore|TelegramApi)/" /tmp/wave106-candidates.txt | head -5
```
Expected: empty output (no excluded paths leaked through).
---
## Task 3: Build the skip-list via preemptive regex
**File:** none (read-only).
- [ ] **Step 1: Run the combined skip-regex against candidates**
The skip-regex is the union of three tiers from the spec. Run:
```sh
grep -El "\bPostbox\b|\bMediaBox\b|\bMediaResource\b|\bMediaResourceData\b|\bMediaResourceId\b|\bPostboxCoding\b|\bPostboxDecoder\b|\bPostboxEncoder\b|\bMemoryBuffer\b|\bTempBoxFile\b|\bValueBoxKey\b|\bPostboxView\b|\bcombinedView\b|\bPeerId\b|\bMessageId\b|\bMediaId\b|\bMessageIndex\b|\bMessageAndThreadId\b|\bPeerNameIndex\b|\bStoryId\b|\bItemCollectionId\b|\bFetchResourceSourceType\b|\bFetchResourceError\b|\bPeer\b|\bMessage\b|\bMedia\b" \
$(cat /tmp/wave106-candidates.txt) \
| sort -u > /tmp/wave106-skiplist.txt
wc -l /tmp/wave106-skiplist.txt
```
Expected: most of the candidate list (likely 600-1100 files matched) — `\bPeer\b`, `\bMessage\b`, `\bMedia\b` are deliberately broad and catch many false positives. False positives are SAFE — they just mean fewer drops, not bad drops.
- [ ] **Step 2: Compute the drop-list**
Run:
```sh
comm -23 /tmp/wave106-candidates.txt /tmp/wave106-skiplist.txt > /tmp/wave106-droplist.txt
wc -l /tmp/wave106-droplist.txt
head -20 /tmp/wave106-droplist.txt
```
Expected: 5-50 files in the drop-list (wave 93 had 12). If 0, the regex is over-matching — halt and revisit. If >100, the regex is under-matching — halt, expand patterns, re-run.
- [ ] **Step 3: Spot-verify 3 random drop candidates**
Run for each of 3 files from the head of the drop-list:
```sh
head -3 /tmp/wave106-droplist.txt | while read f; do
echo "=== $f ==="
grep -nE "Postbox|MediaBox|MediaResource|PeerId|MessageId|MediaId|MessageIndex" "$f" | head -5
done
```
Expected: Only `import Postbox` line appears. If any other Postbox-token appears, the file should have been skipped — add the missing pattern to the regex in Step 1, redo Steps 1-2, and re-spot-check.
---
## Task 4: Drop `import Postbox` from drop-list files
**Files:** every path listed in `/tmp/wave106-droplist.txt`.
- [ ] **Step 1: Read each drop-list file's import block to locate the exact `import Postbox` line**
For each file in the drop-list, the line is `import Postbox` (exact match, no whitespace variations expected). Use a single-purpose `sed` to remove it from all drop-list files:
```sh
while read f; do
sed -i '' '/^import Postbox$/d' "$f"
done < /tmp/wave106-droplist.txt
```
The `sed -i ''` syntax is BSD/macOS specific — required on Darwin.
- [ ] **Step 2: Verify the imports were removed**
Run:
```sh
grep -lE "^import Postbox$" $(cat /tmp/wave106-droplist.txt) | wc -l
```
Expected: 0 (no file in the drop-list still contains `import Postbox`).
- [ ] **Step 3: Verify no other lines were touched**
Run:
```sh
git diff --stat | tail -5
git diff --shortstat
```
Expected: same number of files modified as drop-list size. Each file should show `-1` insertion (or `-1` deletion). If any file shows multiple deletions, something went wrong — `git checkout -- $(cat /tmp/wave106-droplist.txt)` and investigate.
---
## Task 5: Build iteration 1 — capture failures
**File:** none (build only).
- [ ] **Step 1: Run the build with `--continueOnError`**
Run:
```sh
source ~/.zshrc 2>/dev/null && \
python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 \
--configuration=debug_sim_arm64 \
--continueOnError 2>&1 | tee /tmp/wave106-build-iter1.log
```
Expected: Build completes (with errors). Wall-clock 30-260s depending on cache state.
- [ ] **Step 2: Extract failing files**
Run:
```sh
grep -E ":[0-9]+:[0-9]+: error:" /tmp/wave106-build-iter1.log \
| awk -F: '{print $1}' \
| sort -u > /tmp/wave106-restore-iter1.txt
wc -l /tmp/wave106-restore-iter1.txt
cat /tmp/wave106-restore-iter1.txt
```
Expected: a subset of the drop-list. Wave 93 saw 5 of 12 needing restore. If the count > 50% of drop-list, the regex is missing a major pattern — HALT, analyze the failure cluster, add the missing pattern to Task 3 Step 1, restart from Task 4.
- [ ] **Step 3: Verify no errors in TelegramCore/Postbox/TelegramApi**
Run:
```sh
grep -E "^submodules/(TelegramCore|Postbox|TelegramApi)/" /tmp/wave106-restore-iter1.txt
```
Expected: empty. If non-empty: HALT immediately, `git checkout -- submodules/`, and revert the wave — scope drift indicates the candidate filter or sed pattern is wrong.
---
## Task 6: Restore failing files (iter 1)
**Files:** every path in `/tmp/wave106-restore-iter1.txt`.
- [ ] **Step 1: Re-add `import Postbox` to each failing file**
Use awk uniformly (BSD `sed -i '' 'i\'` line-continuation is fragile inside shell loops). Insert `import Postbox` immediately before `import TelegramCore` if present, else immediately after the first existing `import ` line:
```sh
while read f; do
awk '
BEGIN { added = 0 }
!added && /^import TelegramCore$/ { print "import Postbox"; print; added = 1; next }
{ print }
END {
if (!added) {
# fallback path was not used — try post-first-import injection
# (this END block is a no-op; awk cannot re-emit lines after END)
}
}
' "$f" > "$f.tmp"
if ! grep -q "^import Postbox$" "$f.tmp"; then
# no TelegramCore anchor found — fall back to "after first import"
awk '
BEGIN { added = 0 }
!added && /^import / { print; print "import Postbox"; added = 1; next }
{ print }
' "$f" > "$f.tmp"
fi
mv "$f.tmp" "$f"
done < /tmp/wave106-restore-iter1.txt
```
- [ ] **Step 2: Verify restorations**
Run:
```sh
grep -L "^import Postbox$" $(cat /tmp/wave106-restore-iter1.txt)
```
Expected: empty (every file in the restore list now contains `import Postbox` again).
- [ ] **Step 3: Update the working drop-list**
Run:
```sh
comm -23 /tmp/wave106-droplist.txt /tmp/wave106-restore-iter1.txt > /tmp/wave106-final-droplist.txt
wc -l /tmp/wave106-final-droplist.txt
```
This is the current "successfully dropped" set.
---
## Task 7: Build iteration 2 — verify clean (or iterate further)
**File:** none (build only).
- [ ] **Step 1: Re-run the build with `--continueOnError`**
Run:
```sh
source ~/.zshrc 2>/dev/null && \
python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 \
--configuration=debug_sim_arm64 \
--continueOnError 2>&1 | tee /tmp/wave106-build-iter2.log
```
- [ ] **Step 2: Extract any new failures**
Run:
```sh
grep -E ":[0-9]+:[0-9]+: error:" /tmp/wave106-build-iter2.log \
| awk -F: '{print $1}' \
| sort -u > /tmp/wave106-restore-iter2.txt
wc -l /tmp/wave106-restore-iter2.txt
```
- [ ] **Step 3: If non-empty, repeat Task 6 with `iter2.txt` and run Task 7 again as iter3.**
Stop when:
- `restore-iterN.txt` is empty → proceed to Task 8.
- `N == 5` → HALT (diminishing returns); commit what is green via Task 9.
Each repeat: substitute `iter1` → `iter2` → `iter3` etc. throughout. Update the final-droplist after each restore: `comm -23 /tmp/wave106-final-droplist.txt /tmp/wave106-restore-iterN.txt > /tmp/wave106-final-droplist.txt.new && mv /tmp/wave106-final-droplist.txt.new /tmp/wave106-final-droplist.txt`.
---
## Task 8: Final clean build (no `--continueOnError`)
**File:** none (build only).
- [ ] **Step 1: Run a clean build to confirm no inter-module ordering issue was masked**
Run:
```sh
source ~/.zshrc 2>/dev/null && \
python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 \
--configuration=debug_sim_arm64 2>&1 | tail -30
```
Expected: build success, no `error:` lines in the tail. If failure: an inter-module visibility issue exists that `--continueOnError` masked. Restore the final-droplist file(s) implicated by the error, repeat Task 7 / Task 8.
---
## Task 9 (optional): BUILD-dep sweep
**Files:** various `submodules/*/BUILD` files.
This step removes `//submodules/Postbox` from any Bazel package whose Swift sources no longer contain `import Postbox`. Skip this task if iteration time is constrained — the import drops alone are the core wave value; deps trim is housekeeping.
- [ ] **Step 1: Find packages whose `BUILD` still depends on `//submodules/Postbox` but whose `Sources/**/*.swift` no longer imports it**
Run:
```sh
for build in $(find submodules -name BUILD -not -path "submodules/Postbox/*"); do
pkg_dir=$(dirname "$build")
if grep -q "//submodules/Postbox" "$build" 2>/dev/null; then
if ! grep -rq "^import Postbox$" "$pkg_dir" --include="*.swift" 2>/dev/null; then
echo "$build"
fi
fi
done > /tmp/wave106-build-deps-candidates.txt
wc -l /tmp/wave106-build-deps-candidates.txt
cat /tmp/wave106-build-deps-candidates.txt
```
Expected: 0-5 candidates. If 0, skip to Task 10.
- [ ] **Step 2: For each candidate BUILD, locate the `//submodules/Postbox` line and remove it via Edit**
Note that BUILD files often list deps as either `"//submodules/Postbox"` (string) or via aliases. Use Read to inspect each, then Edit to drop just the dep line. The exact string pattern varies — typically `"//submodules/Postbox",` on its own line within a `deps = [ ... ]` block.
For each candidate file, Read the lines around the match, then Edit to remove the line preserving the surrounding bracket structure.
- [ ] **Step 3: Re-run the clean build (no `--continueOnError`) to confirm no dep was load-bearing**
Run the same command as Task 8 Step 1.
If failure: a transitive dep was being satisfied through Postbox. Restore the dep line(s) implicated by the error and re-run.
---
## Task 10: Commit the wave
**File:** `git`.
- [ ] **Step 1: Inspect final diff statistics**
Run:
```sh
git diff --stat
git diff --shortstat
```
Expected: N file modifications, all `-1` line changes (just `import Postbox` lines), possibly plus a small number of BUILD diffs from Task 9.
- [ ] **Step 2: Confirm only allowed paths are touched**
Run:
```sh
git diff --name-only | grep -vE "^submodules/" | head -5
git diff --name-only | grep -E "^submodules/(Postbox|TelegramCore|TelegramApi)/" | head -5
```
Both expected: empty. If either has output: HALT — rogue changes exist; investigate before committing.
- [ ] **Step 3: Stage only the modified Swift and BUILD files**
Run:
```sh
git add $(git diff --name-only)
git status --short
```
Expected: all changes staged with `M`. Untracked dirs (`build-system/tulsi/`, `submodules/TgVoip/`, `third-party/libx264/`) and the `m` submodule marker remain untouched.
- [ ] **Step 4: Commit with the wave message**
Substitute `<N>` with the count from `/tmp/wave106-final-droplist.txt`, `<M>` with the total restored across iterations, and `<K>` with the BUILD deps removed (0 if Task 9 skipped).
```sh
N=$(wc -l < /tmp/wave106-final-droplist.txt | tr -d ' ')
M=$(cat /tmp/wave106-restore-iter*.txt 2>/dev/null | sort -u | wc -l | tr -d ' ')
K=$(git diff --cached --name-only | grep -c BUILD)
git commit -m "$(cat <<EOF
Postbox -> TelegramEngine wave 106 (import drop sweep round 2)
Speculative drop of \`import Postbox\` in $N files where the last
Postbox-typed symbol reference was peeled off by waves 94-105.
Methodology: pattern-based pre-flight skip + drop + build-feedback
restore loop (wave-93-validated recipe). $M files restored after build.
$K BUILD deps removed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
git status --short
```
Expected: clean commit, working tree returns to the known-persistent untracked-only state.
---
## Task 11: Update memory file with wave outcome
**File:** `/Users/isaac/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/project_postbox_refactor_next_wave.md`.
- [ ] **Step 1: Read the current memory file to find the recent-commits section**
Read the top section listing wave commits.
- [ ] **Step 2: Insert a wave-106 line below the wave-105 entry**
Append (substituting the actual commit hash from `git log -1 --format=%H | head -c 10`):
```markdown
- `<HASH>` — wave 106: speculative `import Postbox` drop sweep round 2. <N> files dropped, <M> restored after build feedback. Methodology re-run of wave 93 (`72de7c4fd5`) with expanded pre-flight regex (added bare-name escapes `\bPeer\b`/`\bMessage\b`/`\bMedia\b` per wave-93 lesson). <K> BUILD deps removed. <iter-count> build cycles.
```
Update the memory file's `description:` frontmatter to reflect wave 106 as the latest.
---
## Halt-and-revert recipe (if anything goes seriously wrong)
If at any point the build fails in TelegramCore/Postbox/TelegramApi, or iteration count exceeds 5 with non-trivial residue, or scope drifts beyond the spec:
```sh
git checkout -- submodules/
git status --short # should match the pre-flight expected output
```
The wave is fully reversible until Task 10 commits.
---
## Plan Self-Review Notes
- **Spec coverage:** Tasks 1-11 map 1:1 to the 8-step procedure in the spec plus pre-flight (Task 1) and post-commit memory update (Task 11). Halt conditions appear in Tasks 5/7/9 and the final halt-and-revert recipe.
- **Placeholder scan:** No TBDs/TODOs. All `<N>`/`<M>`/`<K>`/`<HASH>` are explicitly substituted via shell expansion in Step 4 of Task 10.
- **Type/method consistency:** Single-purpose tasks operating on filesystem and grep — no method-name drift risk.
- **Iteration shape:** Tasks 5-7 form the iteration loop; Task 8 is the validation gate; Task 9 is optional housekeeping; Task 10 commits.

223
docs/superpowers/plans/2026-04-26-postbox-wave-106-pivot-engine-data-incremental.md
View file

@ -1,223 +0,0 @@
# Wave 106 Pivot: engine `data(resource:incremental:)` facade extension + 1-site drain
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task.
**Goal:** Pivot wave 106 from the abandoned import-drop sweep to a small facade-extension wave. Add an `incremental: Bool = false` parameter to `TelegramEngine.Resources.data(resource:)`, drain the 1 live `account.postbox.mediaBox.resourceData(..., option: .incremental(...))` consumer site (`ChatInterfaceStateContextMenus.swift:1327`).
**Background — wave 106 (pure sweep) abandoned 2026-04-26:** Inventory of 576 candidate files showed every one of them legitimately references at least one Postbox-tier token (Postbox/MediaBox/MediaResource/protocol-Peer/protocol-Message/protocol-Media/typealiased identifier). Wave 93's pure import-sweep pattern is exhausted at the file granularity — no single-file orphans remain. See spec `docs/superpowers/specs/2026-04-26-postbox-wave-106-import-drop-sweep-design.md` (committed) for the abandoned methodology.
**Architecture:** Wave-shape G (facade addition + small validation drain). 2 file edits (1 in TelegramCore, 1 in TelegramUI). Single-iter expected.
**Tech Stack:** Swift, Bazel via `Make.py`, no unit tests. Verification is the full-project debug-sim-arm64 build.
**Iteration budget:** 1-2 (TelegramCore touch incurs ~210-260s build).
---
## File Structure
| File | Role | Edits |
|---|---|---|
| `submodules/TelegramCore/Sources/TelegramEngine/Resources/TelegramEngineResources.swift` | Add `incremental` param to `data(resource:)` facade | 1 Edit (signature + body) |
| `submodules/TelegramUI/Sources/ChatInterfaceStateContextMenus.swift` | Migrate L1327 call site | 1 Edit (call + `data.complete` → `data.isComplete`) |
---
## Task 1: Extend the engine `data(resource:)` facade with `incremental:` parameter
**File:** `submodules/TelegramCore/Sources/TelegramEngine/Resources/TelegramEngineResources.swift`
- [ ] **Step 1: Edit the `data(resource:)` facade signature and body**
Find at line 453-466:
```swift
public func data(
resource: EngineMediaResource,
pathExtension: String? = nil,
waitUntilFetchStatus: Bool = false,
attemptSynchronously: Bool = false
) -> Signal<EngineMediaResource.ResourceData, NoError> {
return self.account.postbox.mediaBox.resourceData(
resource._asResource(),
pathExtension: pathExtension,
option: .complete(waitUntilFetchStatus: waitUntilFetchStatus),
attemptSynchronously: attemptSynchronously
)
|> map { EngineMediaResource.ResourceData($0) }
}
```
Replace with:
```swift
public func data(
resource: EngineMediaResource,
pathExtension: String? = nil,
waitUntilFetchStatus: Bool = false,
incremental: Bool = false,
attemptSynchronously: Bool = false
) -> Signal<EngineMediaResource.ResourceData, NoError> {
let option: MediaBoxFetchDataOption = incremental
? .incremental(waitUntilFetchStatus: waitUntilFetchStatus)
: .complete(waitUntilFetchStatus: waitUntilFetchStatus)
return self.account.postbox.mediaBox.resourceData(
resource._asResource(),
pathExtension: pathExtension,
option: option,
attemptSynchronously: attemptSynchronously
)
|> map { EngineMediaResource.ResourceData($0) }
}
```
The `incremental` parameter is inserted between `waitUntilFetchStatus` and `attemptSynchronously`. Existing call sites passing only labeled-or-trailing arguments remain compatible because Swift requires labels for these (no positional ordering issue).
---
## Task 2: Migrate the consumer call site
**File:** `submodules/TelegramUI/Sources/ChatInterfaceStateContextMenus.swift`
- [ ] **Step 1: Edit L1327 — replace `account.postbox.mediaBox.resourceData(...)` with engine facade**
Find at line 1327:
```swift
let _ = (context.account.postbox.mediaBox.resourceData(largest.resource, option: .incremental(waitUntilFetchStatus: false))
```
Replace with:
```swift
let _ = (context.engine.resources.data(resource: EngineMediaResource(largest.resource), incremental: true)
```
- [ ] **Step 2: Rename downstream `data.complete` field access to `data.isComplete`**
Find at line 1330:
```swift
if data.complete, let imageData = try? Data(contentsOf: URL(fileURLWithPath: data.path)) {
```
Replace with:
```swift
if data.isComplete, let imageData = try? Data(contentsOf: URL(fileURLWithPath: data.path)) {
```
The `.path` field name is unchanged (both `MediaResourceData` and `EngineMediaResource.ResourceData` use `path`).
---
## Task 3: Verify residue and build
- [ ] **Step 1: Residue grep for the migrated expression**
Run:
```sh
grep -nE "context\.account\.postbox\.mediaBox\.resourceData\(.*option: \.incremental" submodules/TelegramUI/Sources/ChatInterfaceStateContextMenus.swift
```
Expected: empty.
- [ ] **Step 2: Verify the new facade signature compiles without breaking existing callers**
Existing call sites of `engine.resources.data(resource:)` use these forms (per wave 32+ history):
- `engine.resources.data(resource: EngineMediaResource(x))` — default args, fine
- `engine.resources.data(resource: EngineMediaResource(x), pathExtension: "ext")` — labeled, fine
- `engine.resources.data(resource: EngineMediaResource(x), waitUntilFetchStatus: true)` — labeled, fine
Adding `incremental: Bool = false` between `waitUntilFetchStatus` and `attemptSynchronously` doesn't reorder existing call sites because all parameters use labels. Confirm with grep:
```sh
grep -rnE "engine\.resources\.data\(resource:" submodules --include="*.swift" | wc -l
```
Just for visibility — number of existing call sites that should remain green.
- [ ] **Step 3: Run the full clean build**
Run:
```sh
source ~/.zshrc 2>/dev/null && \
python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 \
--configuration=debug_sim_arm64 2>&1 | tail -30
```
Expected: build success, no errors. If failure, fix in place and re-run (single iter expected).
---
## Task 4: Commit the wave
- [ ] **Step 1: Inspect diff**
Run:
```sh
git diff --stat
```
Expected: 2 files modified.
- [ ] **Step 2: Stage and commit**
```sh
git add submodules/TelegramCore/Sources/TelegramEngine/Resources/TelegramEngineResources.swift \
submodules/TelegramUI/Sources/ChatInterfaceStateContextMenus.swift
git commit -m "$(cat <<'EOF'
Postbox -> TelegramEngine wave 106 (pivot: engine data() incremental facade + 1-site drain)
Original wave 106 pure import-drop sweep abandoned: 576 candidate files
all genuinely reference Postbox-tier tokens; wave 93's pattern exhausted
at file granularity (no single-file orphans remain).
Pivot: extend engine.resources.data(resource:) facade with
`incremental: Bool = false` parameter. Drain the 1 live consumer site
(ChatInterfaceStateContextMenus:1327) plus consumer-side
`data.complete` -> `data.isComplete` rename.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```
---
## Task 5: Update memory file
**File:** `/Users/isaac/.claude/projects/-Users-isaac-build-telegram-telegram-ios/memory/project_postbox_refactor_next_wave.md`
- [ ] **Step 1: Update frontmatter description and append wave 106 entries**
Update the `description:` line to reflect wave 106 (pivot).
Append two lines under the recent-commits section:
- One for the abandoned wave 106 import-drop sweep with the key finding (sweep pattern exhausted, save future sessions a re-attempt).
- One for the wave 106 pivot commit hash with cost/yield.
- [ ] **Step 2: Append a "Wave 106 ABANDONED" subsection** documenting the import-sweep exhaustion finding so future sessions don't re-attempt the pure sweep shape. Note the regex set tested and the conclusion ("any consumer file with `import Postbox` legitimately needs at least one Tier-1/Tier-2 token").
---
## Halt-and-revert recipe
If build fails for non-trivial reasons (more than 1 iter):
```sh
git checkout -- submodules/TelegramCore/Sources/TelegramEngine/Resources/TelegramEngineResources.swift \
submodules/TelegramUI/Sources/ChatInterfaceStateContextMenus.swift
git status --short
```
Wave is reversible until Task 4 commits.

170
docs/superpowers/specs/2026-04-16-postbox-to-telegramengine-refactor-wave-1-design.md
View file

@ -1,170 +0,0 @@
# Postbox → TelegramEngine refactor, wave 1
## Goal
Gradually eliminate direct `import Postbox` from consumer submodules by routing all data access through `TelegramEngine` (`.data.get` / `.data.subscribe` and engine-owned functions). Behavior must be preserved exactly — this is a dependency-shape refactor, not a semantic change.
This spec covers **wave 1**: the first 10 single-import leaf modules, refactored in bottom-up dependency order. Subsequent waves will be covered by their own specs.
## Non-goals
- No refactor inside `TelegramCore` itself — it owns `TelegramEngine` and will keep importing Postbox.
- No refactor inside `Postbox`.
- No behavior or UX changes. No unrelated cleanup.
- No edits to modules outside the 10 chosen by the selection rule.
- Within wave-1 modules, switching Postbox-typed names to their engine typealiases (`PeerId` → `EnginePeer.Id`, etc.) is required and in scope; introducing new engine *wrapper types* that re-encode data is out of scope.
- No generic `engine.transaction { postbox in … }` escape hatch.
## Guiding rules
1. Consumers only. `TelegramCore` does **not** `@_exported import Postbox`, so once a module drops its Postbox import every remaining Postbox-type reference must be switched to the engine-typealiased equivalent (`PeerId` → `EnginePeer.Id`, `MessageId` → `EngineMessage.Id`, `MessageIndex` → `EngineMessage.Index`, `MessageTags` → `EngineMessage.Tags`, `MediaId` → `EngineMedia.Id`, etc.). These aliases are identical to their Postbox originals, so the swap is behavior-preserving.
2. **Never typealias the `Postbox` class itself** (or other large umbrella API surfaces such as `Account` or `MediaBox`). Aliasing an umbrella type with something like `EnginePostbox = Postbox` renames without encapsulating — the consumer still has access to the full Postbox API through the alias. It defeats the purpose of the refactor. Narrow utility typealiases (`MemoryBuffer`, `PostboxDecoder`, `PostboxEncoder`, `AdaptedPostboxDecoder`, `MediaResource`, etc.) remain allowed and expected; the ban is specifically on aliasing the large facade types.
3. Prefer existing `Engine*` wrapper types (`EnginePeer`, `EngineMessage`, `EngineMediaResource`) and engine methods; add new engine wrappers only when a call site clearly needs one.
4. Before adding any new engine wrapper, search `submodules/TelegramCore/Sources/TelegramEngine/` for an equivalent by name and shape. Record the search result in the commit that adds the wrapper.
5. Bottom-up dependency order across modules.
6. Full project build after each module, using the command from the global `CLAUDE.md`.
7. A module is done when: no `import Postbox` in its `.swift` files, no `//submodules/Postbox:Postbox` entry in its `BUILD`, full build green, commits landed.
### Abandonment protocol
If a module can only be refactored by either (a) typealiasing an umbrella type banned by rule 2, or (b) editing a module outside the wave-1 list, the module is **abandoned for this wave**. Record it in the plan (mark the task Abandoned with the reason) and reduce the wave's done-count accordingly. Do not substitute a new module mid-wave; the wave's scope is fixed at plan time.
## Wave-1 scope: selecting the 10 modules
### Candidate pool
The 30 submodules that currently have Postbox imports in exactly one `.swift` file:
`ActionSheetPeerItem, ChatInterfaceState, ChatListSearchRecentPeersNode, ChatSendMessageActionUI, ContactListUI, DirectMediaImageCache, DrawingUI, FetchManagerImpl, GalleryData, HorizontalPeerItem, ICloudResources, InAppPurchaseManager, InstantPageCache, InviteLinksUI, ItemListAvatarAndNameInfoItem, ItemListPeerItem, ItemListStickerPackItem, MapResourceToAvatarSizes, PhotoResources, PlatformRestrictionMatching, PresentationDataUtils, PromptUI, SaveToCameraRoll, SelectablePeerNode, ShareItems, SoftwareVideo, StickerPeekUI, StickerResources, TelegramIntents, TelegramNotices`
### Selection rule
The implementation plan runs a deterministic selection pass up-front:
1. Parse each candidate's `BUILD` to compute a reverse-dependency count over the candidate pool (how many other candidates depend on it). Leaves have count 0.
2. Sort by reverse-dep count ascending, then alphabetical. Take the first 10. Write the chosen list into the plan so execution is reproducible.
3. If during execution a chosen module transitively needs a Postbox type not yet exposed via a `TelegramCore` re-export, stop, record the blocker, and skip to the next candidate in the selection-rule ordering — keeping the wave at 10 completed modules.
### Explicitly deferred (future waves, not this spec)
- `TelegramUI` (478 files), `SettingsUI` (44), `TelegramCallsUI` (23), `GalleryUI` (16), `PassportUI` (14), `ChatListUI` (13), `AccountContext` (13), and every other module not in the chosen 10.
- `TelegramCore` (non-goal, ever).
## Per-module playbook
Each of the 10 modules follows the same deterministic sequence.
### 1. Inventory
List every Postbox API referenced in the module. Each reference falls into one of:
- **Type reference only** — signature or local variable uses a Postbox-defined type (`Peer`, `MessageId`, `Media`, `CachedPeerData`, …). Usually resolvable by `TelegramCore` re-exports or an existing `Engine*` type.
- **`postbox.mediaBox.*`** — media resource access.
- **`account.postbox.transaction { … }`** — read/write transaction.
- **`postbox.combinedView / subscribe(...)` with `PostboxViewKey`** — view subscription.
- **`account.postbox.mediaBox` / `postbox.mediaBox` as a parameter** — plumbing through a public signature.
### 2. Map each call site to its replacement
In this priority order:
1. An existing `TelegramEngine.data.get` / `.subscribe` on a `TelegramEngine.EngineData.Item…`.
2. An existing engine function under `TelegramEngine.{peers, messages, accountData, resources, …}`.
3. An existing re-export from `TelegramCore` (for type-only references).
4. A **new** thin wrapper added to the appropriate `TelegramEngine/<Area>/` file (see wrapper policy below). Added in `TelegramCore` in a separate preparatory commit before the consumer edit.
### 3. Edit the consumer
Replace call sites. Function signatures that took `Postbox` as a parameter become signatures taking `TelegramEngine` (or `AccountContext` where already available in the call site). Public-API changes in these leaf modules are acceptable because no other module currently imports them in a way that depends on Postbox types — verified during step 1. Any break discovered at build time is fixed at the call site in the same commit, or the module is skipped if the fix would require changing a module outside the wave.
### 4. Drop the dependency
- Remove `import Postbox` from every file.
- Remove `"//submodules/Postbox:Postbox"` from the module's `BUILD`.
### 5. Build
Run the full project build from the global `CLAUDE.md`:
```
PATH=/opt/homebrew/opt/ruby/bin:`gem environment gemdir`/bin:$PATH \
python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development \
--gitCodesigningUseCurrent \
--buildNumber 1 \
--configuration debug_sim_arm64
```
The module is not marked done until the full build is green. Fix failures in place before moving on.
### 6. Commit
Commit structure per module, one or two commits:
1. `TelegramCore: add <wrapper name>` — optional, only if new engine wrappers were needed.
2. `<ModuleName>: drop direct Postbox dependency` — consumer edits plus BUILD change.
## Engine-wrapper policy
When a call site has no existing engine equivalent, the wrapper is added in `TelegramCore` **before** the consumer edit, in a **separate commit**.
### Where wrappers go
- **Data reads and subscriptions** → new `TelegramEngine.EngineData.Item.<Area>.<Name>` struct alongside its peers in `submodules/TelegramCore/Sources/TelegramEngine/Data/<Area>Data.swift`. The item's `extract` maps the underlying `PostboxView` to an engine-typed result.
- **Imperative signal-returning calls** → new method on the matching area class (`Peers`, `Messages`, `Resources`, `AccountData`, …) inside `submodules/TelegramCore/Sources/TelegramEngine/<Area>/`.
- **Media-resource access** → extended on `TelegramEngine.resources` rather than exposing `MediaBox` to consumers. For example: `engine.resources.data(…)`, `engine.resources.fetch(…)`, `engine.resources.status(…)`. Each forwards to `account.postbox.mediaBox.*` internally.
- **Ad-hoc transactions that a consumer was running directly** → a specific purpose-built method on the appropriate area, never a generic transaction escape hatch. If only one call site needs the logic and it's trivial, inline it into a new area method rather than creating a helper.
### Rules for the wrapper itself
- Minimal pass-through. No caching, no extra signal plumbing, no bonus features.
- Return type must be nameable from the consumer **without** importing Postbox. That means: an existing `Engine*` wrapper type (`EnginePeer`, `EngineMessage`, `EngineMediaResource`), an existing engine typealias (`EnginePeer.Id`, `EngineMessage.Id`, …), a Swift primitive, or a new `Engine*` typealias added in the same commit. Do **not** return a bare Postbox type.
- Do not introduce new engine wrapper *structs/classes* that re-encode data (those are out of scope for this wave). A new typealias to make an existing Postbox type reachable under an `Engine*` name is allowed and expected.
- Public.
- Consumer must not need anything else from Postbox after the wrapper is in place.
- No deprecation shim. Existing Postbox-using code paths elsewhere in the codebase stay untouched.
### Discovery step (always runs first)
Before writing any new wrapper, search `submodules/TelegramCore/Sources/TelegramEngine/` for an existing match by name and shape. Document "searched for X, found/not found" in the commit that adds the wrapper, so future waves don't re-invent it.
## Verification
### Per-module static checks (must pass before running the build)
- `grep -R "^import Postbox" submodules/<M>/Sources` returns empty.
- `grep "submodules/Postbox" submodules/<M>/BUILD` returns empty.
### Per-module build check
- Full project build (the command in §Per-module playbook step 5) is green.
- No warnings-as-errors regressions introduced by the refactor.
### Wave-completion check
- All 10 chosen modules satisfy the per-module checks.
- Any new engine wrappers are documented in their respective commits.
## Risks and mitigations
- **Public signature changes in a leaf module break an unexpected caller.** Mitigated by the full build per module. Fix at the call site in the same commit, or skip and move on if the fix would pull in scope beyond the wave.
- **A Postbox view has no equivalent engine data item.** Add a new `EngineData.Item` per the wrapper policy. If the mapping is non-trivial (needs its own result type), skip the module and flag it for a future spec.
- **Transitive Postbox usage through a type the module re-exposes publicly.** Caught during Inventory (step 1). If fixing would require editing another module in the wave's dependency graph, skip.
- **A Postbox type has no engine typealias.** Add the typealias in `TelegramCore` (`EngineXxx = Xxx`) in the preparatory commit, then use it in the consumer. Typealias-only additions are explicitly allowed and cheap.
- **Build times.** Full project build per module is slow but accepted — it gives the strongest signal.
## Follow-ups (not this spec)
- Successive waves for the remaining ~64 modules in bottom-up order, each its own spec.
- `TelegramUI` (478 files) and `SettingsUI` (44) will likely need a bespoke approach because of scale; they get their own spec when the time comes.
- Whether `AccountContext` itself should eventually stop importing Postbox is deferred.
## Done definition for this spec
- Every module in the wave-1 list is either **done** (zero `import Postbox` in its sources, no `//submodules/Postbox:Postbox` in its `BUILD`) or explicitly marked **abandoned** with a recorded reason in the plan.
- Full project build is green at wave end.
- Any new engine wrappers added along the way are documented in their commits.

245
docs/superpowers/specs/2026-04-17-listview-pin-to-edge-design.md
View file

@ -1,245 +0,0 @@
# ListView pin-to-edge first-pinned-item design
## Goal
Give `submodules/Display/Source/ListView.swift` the ability to pin a single "first pinned item" to the bottom edge of the scrolling area. The item's `apparentFrame.maxY` should sit at `visibleSize.height - insets.bottom` when the combined height of items with smaller indices ("items above", in list coordinates) is less than the available scrolling-area height. When items above grow past that threshold, the pinning gracefully disengages and the list scrolls normally.
This produces, in a flipped-chat consumer, the "AI-chat" UX in which a newly-sent outgoing message appears pinned to the visual top of the viewport while later additions fill in toward it.
## Non-goals
- Changes to `ListViewItemLayoutParams.availableHeight` or any item-side sizing API.
- A new per-item inset value. The existing `pinToEdgeWithInset: Bool` protocol property (declared on `ListViewItem`, default `false`, currently unread) is repurposed as the trigger; there is no numeric inset argument.
- Coordinating with `stackFromBottom` or `stackFromBottomInsetItemFactor`. Where both mechanisms contribute a top-inset, the existing `max(effectiveInsets.top, …)` chain combines them without additional logic.
- Defining behavior for items with an index greater than the pinned item's. Consumer contract: when a consumer sets `pinToEdgeWithInset = true` on an item, that item must be the highest-index flagged item (in practice, the last item in the data array). Items beyond the pinned item render at their natural frames; the pinning guarantee applies only relative to items with smaller indices.
- Unit tests. The project has no test harness; verification is via full-project build plus manual exercise in a consumer (see "Verification").
## Mechanism
### Trigger rule
Among materialized item nodes (`self.itemNodes`), find the one with the smallest `index` whose `self.items[index].pinToEdgeWithInset == true`. Call it the pinned node. If there is no such node (no flagged item, or the flagged item is outside the recycling window), pin-to-edge behavior is inert for that frame.
### Adjustment formula
```
visibleArea = visibleSize.height - self.insets.top - self.insets.bottom
totalAboveAndPinned = Σ apparentBounds.height for itemNodes with index ≤ lowestPinnedIndex
pinTopAdjustment = max(0, visibleArea - totalAboveAndPinned)
```
**Height source: `apparentBounds.height`, not `frame.size.height`.** `apparentBounds.height` returns `self.apparentHeight`, which `insertNodeAtIndex` (at [ListView.swift:2439](submodules/Display/Source/ListView.swift:2439)) sets to `0.0` for animated insertions and grows via `addApparentHeightAnimation` over the insertion animation's duration. It is *essential* that the helper use this animated value: the ListView's per-tick `vSync` handler (around [ListView.swift:4842](submodules/Display/Source/ListView.swift:4842)) calls `snapToBounds` after each apparentHeight update, so the pin inset is recomputed with the current animated height every frame. With `apparentBounds.height`:
- **Insertion above pinned** (the critical case): at insertion, new item `X` has `apparentHeight = 0`, so `totalAboveAndPinned` is unchanged, `pinTopAdjustment` is unchanged, `effectiveInsets.top` is unchanged, and the pinned item stays exactly where it was. As `X`'s apparentHeight grows by `dh` per tick, `totalAboveAndPinned` grows by `dh`, `pinTopAdjustment` shrinks by `dh`, and `snapToBounds` shifts items by `-dh` via its `topItemEdge > effectiveInsets.top` clamp; the pinned item's `origin.y` decreases by `dh` while items after `X` (which offsetRanges shifts by `+dh` earlier in the same vSync) are at `pinned.y + dh − dh = pinned.y` — stationary throughout the animation.
- **Initial animated insertion of a pinned item**: `X` starts at `origin.y` = pinned bottom-edge with `apparentHeight = 0` (invisible). As apparentHeight grows by `dh`, `effectiveInsets.top` shrinks by `dh` and `snapToBounds` shifts `origin.y` by `-dh`. `apparentFrame.maxY = origin.y + apparentHeight` stays exactly at the bottom edge for the whole animation; the item appears to grow upward from the bottom edge into its final pinned position.
Using `frame.size.height` would freeze `totalAboveAndPinned` at its final value on the first tick, so `effectiveInsets.top` would jump to its post-animation value immediately. Insertion above pinned would drag the pinned item up by the new item's full real height on frame 0, then the apparentHeight animation would leave it there — breaking the "pinned stays put" invariant. Initial animated layout would land the item at its final `origin.y` with `apparentHeight = 0`, then grow its content downward into a fixed slot instead of upward from the bottom edge, which is the wrong visual.
The formula is built from item *heights*, not positions, so it is idempotent: re-running `snapToBounds` or `updateScroller` after a snap offset has already been applied yields the same `pinTopAdjustment`. (A position-based formula would read the post-snap `maxY` and compute 0 on the next pass, undoing the shift.)
`visibleArea` uses `self.insets`, not `effectiveInsets`, so the threshold at which pinning disengages is purely geometric and is not coupled to other contributors to `effectiveInsets.top` (e.g. `stackFromBottomInsetItemFactor`). Combining with those contributors happens at the application site via `max(…)`.
### Partial-materialization guard
Pinning requires the full height of items `[0, lowestPinnedIndex]` to be known. If items[0] is not materialized (not in `self.itemNodes`), some leading items are off-screen above — which can only happen when the scroll area is already full of content above the pinned item — and pinning is then inert for that frame. The helper therefore returns 0 unless an itemNode with `index == 0` is present among the materialized nodes. `ListView`'s recycling window is a contiguous range of indices, so `items[0]` materialized implies `items[0…lowestPinnedIndex]` all materialized.
### Application
At each call site that computes `effectiveInsets`, after the existing `stackFromBottomInsetItemFactor` branch:
```swift
let pinToEdgeTopInset = self.calculatePinToEdgeTopInset()
if pinToEdgeTopInset > 0.0 {
effectiveInsets.top = max(effectiveInsets.top, self.insets.top + pinToEdgeTopInset)
}
```
This piggybacks on the virtual-top-inset mechanism that `stackFromBottomInsetItemFactor` already uses: raising `effectiveInsets.top` shifts the scroll content downward by that amount, positioning the pinned item's `maxY` at the bottom edge. When `pinTopAdjustment` is 0 (items above have reached the available area, or the guard tripped), no contribution is made and scrolling is ordinary.
### Inset-transition correction
There is a third integration point, separate from the two `effectiveInsets` call sites: the inset-transition code in `deleteAndInsertItemsTransaction` around [ListView.swift:3167-3188](submodules/Display/Source/ListView.swift:3167). This block runs whenever `updateSizeAndInsets` is non-nil and shifts every item's frame by an `offsetFix` in order to keep the list visually coherent across the inset/size change.
In the "top-inset" branch (the `else` at line 3173), the existing formula is:
```swift
offsetFix = updateSizeAndInsets.insets.top - self.insets.top
```
When pinning is engaged, this is wrong: a change in `self.insets.top` is exactly compensated by an opposite change in `pinTopAdjustment` (since `visibleArea = visibleSize.height - insets.top - insets.bottom` moves in lockstep with `insets.top`), so the *effective* top inset (`insets.top + pinTopAdjustment`) doesn't move. But `offsetFix` uses only the raw top delta, so it shifts every item's frame by `top_delta`. The list visibly jumps by that amount until the next `snapToBounds`/`updateScroller` pass corrects it — a keyboard toggle produces a jitter equal to the keyboard's top-inset contribution.
The correction: capture `self.calculatePinToEdgeTopInset()` before *either* `self.visibleSize` or `self.insets` is reassigned; compute it again after both are updated; and, in the top-inset branch only, add `(updated - previous)` to `offsetFix`. This makes `offsetFix` equal the *effective* top-inset delta rather than the raw one.
**Ordering matters.** The existing code updates `self.visibleSize` on [ListView.swift:3165](submodules/Display/Source/ListView.swift:3165) (right after entering the inset-transition branch) and `self.insets` on [ListView.swift:3183](submodules/Display/Source/ListView.swift:3183) (later, just before the `offsetFix` shift is applied). The `previousPinToEdgeTopInset` measurement must happen before line 3165 — not between 3165 and 3183 — because `calculatePinToEdgeTopInset` reads `self.visibleSize` to form `visibleArea`. Measuring after 3165 captures a hybrid state (new visibleSize, old insets) that never existed; the resulting delta is wrong whenever `visibleSize` changes in the same transaction.
Initial layout is the case that surfaces this: the old `self.visibleSize = CGSize.zero`, so `visibleArea ≤ 0` and the helper correctly returns 0 ("no prior pinning") when measured before line 3165. Measured after line 3165, `visibleArea` is the full new screen size and the helper returns a fake "previous" pin inset roughly equal to the real post-transaction pin inset — delta cancels out, and the sign of `offsetFix` flips negative, shifting items in the wrong direction. `snapToBounds` then pulls them back to the right resting position, but the intermediate `offsetFix` value propagates into `sizeAndInsetsOffset` and the `-completeOffset` animation `fromValue`, producing a visible mis-offset on the first frame.
Rotation (which changes both visibleSize and insets in one transaction) has the same structural issue but is less dramatic because the old visibleSize is non-zero.
The other two branches don't need the correction:
- `snapToBottomInsetUntilFirstInteraction` branch (line 3172): its formula `offsetFix = -(new.bottom - old.bottom)` already coincidentally equals `effective_top_delta` when pin is engaged. Working through it: `effective_top_delta = top_delta + pin_delta = top_delta - (top_delta + bottom_delta) = -bottom_delta`.
- `isTracking` branch (line 3170): intentionally sets `offsetFix = 0` and defers repositioning to `snapToBounds`, which already consults pin-aware `effectiveInsets` via the helper.
### scrollToItem override
`scrollToItem` at [ListView.swift:3058-3104](submodules/Display/Source/ListView.swift:3058) computes an offset from the target item's `apparentFrame` and the raw `self.insets`, then shifts every item's frame by that offset. When the target is the pin-to-edge target, most `ListViewScrollPosition` variants (`.top`, `.center`, `.visible`, and `.bottom(nonzero)`) compute an offset that drags the pinned item away from its pinned position; the subsequent `snapToBounds` at [ListView.swift:3198](submodules/Display/Source/ListView.swift:3198) / [3360](submodules/Display/Source/ListView.swift:3360) re-imposes pinning on the next pass. The net visible effect is a transient shift in the pre-snap direction, spurious `didScrollWithOffset` callbacks with the wrong value, and (for animated scrolls) a wrong starting frame for the insertion/scroll animation.
The override: when the target item is the pin-to-edge target (the smallest-index materialized item with `pinToEdgeWithInset == true`, and pinning is actually engaged per `calculatePinToEdgeTopInset() > 0`), bypass the `switch scrollToItem.position` and compute the offset directly as:
```swift
offset = (self.visibleSize.height - insets.bottom) - itemNode.apparentFrame.maxY + itemNode.scrollPositioningInsets.bottom
```
This matches the existing `.bottom(0)` case shape. `apparentFrame.maxY` is the right value because of the same per-tick invariant that makes the helper use `apparentBounds.height`: throughout the animation, `apparentFrame.maxY = origin.y + apparentHeight` stays at the pinned bottom edge, so the offset is `0` at every tick — no spurious shift during an in-flight animation. Using `frame.maxY` instead would produce a nonzero offset equal to `apparentHeight − real_height` during the animation, which would fight the `vSync` snap logic and break the animation.
For non-pinned targets, or for the pinned target when pinning is disengaged (`calculatePinToEdgeTopInset() == 0`), the existing `switch` runs unchanged.
## Code changes
### New helper on `ListViewImpl`
```swift
private func calculatePinToEdgeTopInset() -> CGFloat {
// Pass 1: find the smallest-index flagged item among materialized nodes.
var lowestPinnedIndex: Int = Int.max
for itemNode in self.itemNodes {
guard let index = itemNode.index else { continue }
if index < lowestPinnedIndex && self.items[index].pinToEdgeWithInset {
lowestPinnedIndex = index
}
}
guard lowestPinnedIndex != Int.max else { return 0.0 }
// Pass 2: sum heights of items[0 ... lowestPinnedIndex], and require items[0]
// to be materialized (guarantees items[0 ... lowestPinnedIndex] are all present,
// since the recycling window is contiguous in index).
var totalAboveAndPinned: CGFloat = 0.0
var sawIndexZero = false
for itemNode in self.itemNodes {
guard let index = itemNode.index else { continue }
if index == 0 {
sawIndexZero = true
}
if index <= lowestPinnedIndex {
totalAboveAndPinned += itemNode.apparentBounds.height
}
}
guard sawIndexZero else { return 0.0 }
let visibleArea = self.visibleSize.height - self.insets.top - self.insets.bottom
return max(0.0, visibleArea - totalAboveAndPinned)
}
```
### Call-site diffs
**`snapToBounds(…)` — around [ListView.swift:1181-1185](../../submodules/Display/Source/ListView.swift):**
After the existing `stackFromBottomInsetItemFactor` adjustment of `effectiveInsets.top`, add the `pinToEdgeTopInset` block shown above.
**`updateScroller(…)` — around [ListView.swift:1612-1616](../../submodules/Display/Source/ListView.swift):**
Same diff.
**`deleteAndInsertItemsTransaction(…)` inset-transition block — around [ListView.swift:3162-3188](../../submodules/Display/Source/ListView.swift):**
Capture the pin inset before *either* `self.visibleSize` or `self.insets` is reassigned (i.e., before line 3165 in the current code); track whether the top-inset branch was taken; and after `self.insets` and `self.visibleSize` are updated, add the pin-inset delta to `offsetFix` if the top-inset branch was taken:
```swift
let previousPinToEdgeTopInset = self.calculatePinToEdgeTopInset()
let previousVisibleSize = self.visibleSize
self.visibleSize = updateSizeAndInsets.size
var offsetFix: CGFloat
var offsetFixUsesEffectiveTopInset = false
let insetDeltaOffsetFix: CGFloat = 0.0
if (self.isTracking && !self.allowInsetFixWhileTracking) || isExperimentalSnapToScrollToItem {
offsetFix = 0.0
} else if self.snapToBottomInsetUntilFirstInteraction {
offsetFix = -updateSizeAndInsets.insets.bottom + self.insets.bottom
} else {
offsetFix = updateSizeAndInsets.insets.top - self.insets.top
offsetFixUsesEffectiveTopInset = true
}
offsetFix += additionalScrollDistance
self.insets = updateSizeAndInsets.insets
self.headerInsets = updateSizeAndInsets.headerInsets ?? self.insets
self.scrollIndicatorInsets = updateSizeAndInsets.scrollIndicatorInsets ?? self.insets
self.itemOffsetInsets = updateSizeAndInsets.itemOffsetInsets
self.ensureTopInsetForOverlayHighlightedItems = updateSizeAndInsets.ensureTopInsetForOverlayHighlightedItems
self.visibleSize = updateSizeAndInsets.size
if offsetFixUsesEffectiveTopInset {
let updatedPinToEdgeTopInset = self.calculatePinToEdgeTopInset()
offsetFix += updatedPinToEdgeTopInset - previousPinToEdgeTopInset
}
```
**`scrollToItem` handler — around [ListView.swift:3058-3104](../../submodules/Display/Source/ListView.swift):**
Inside the existing `for itemNode in self.itemNodes { if ... index == scrollToItem.index { ... } }` block, right after `let insets = self.insets` and before the `switch scrollToItem.position`:
```swift
var isPinToEdgeTarget = false
if self.calculatePinToEdgeTopInset() > 0.0,
index >= 0, index < self.items.count,
self.items[index].pinToEdgeWithInset {
isPinToEdgeTarget = true
for otherNode in self.itemNodes {
guard let otherIndex = otherNode.index else { continue }
guard otherIndex >= 0, otherIndex < self.items.count else { continue }
if otherIndex < index, self.items[otherIndex].pinToEdgeWithInset {
isPinToEdgeTarget = false
break
}
}
}
var offset: CGFloat
if isPinToEdgeTarget {
offset = (self.visibleSize.height - insets.bottom) - itemNode.apparentFrame.maxY + itemNode.scrollPositioningInsets.bottom
} else {
switch scrollToItem.position {
// … existing .bottom / .top / .center / .visible cases, unchanged …
}
}
```
The `isPinToEdgeTarget` check re-derives "smallest-index materialized flagged item" rather than factoring a shared helper, to keep the pin-to-edge API surface small (the existing `calculatePinToEdgeTopInset()` helper is the only public-within-file surface). The duplication is ~6 lines.
No other source file is modified. `ListViewItem.pinToEdgeWithInset` stays declared where it already is ([ListViewItem.swift:80](../../submodules/Display/Source/ListViewItem.swift), default `false` via the protocol extension).
## Behavioral consequences
- **Pinning engaged** (items above shorter than available area): the pinned item's `maxY` lands on `visibleSize.height - insets.bottom`; virtual empty space sits above items[0] so the combined content fills the visible area.
- **Pinning disengaging** (items above reach the available area): `totalAboveAndPinned` grows with each insertion above until it meets `visibleArea`; at that point `pinTopAdjustment` is exactly 0 and the list scrolls normally. The transition through the threshold is continuous in `totalAboveAndPinned`, so there is no visual jump.
- **Drag / rubber-band / deceleration**: the pinned item behaves like any other item during gesture-driven scroll; on settle, `snapToBounds` returns the content to its resting position, which (while pinning is engaged) places the pinned item at the bottom edge.
- **Insertion at index 0 while pinning is engaged**: the pinned item's index increments by one; `totalAboveAndPinned` grows by the inserted item's height; `pinTopAdjustment` therefore shrinks by the same amount; and the inflated `effectiveInsets.top` shrinks by the same amount in turn. Working through the arithmetic: the pinned item's final `origin.y = effectiveInsets.top + (totalAboveAndPinned - pinned.height)` stays identical before and after, so the pinned item is visually stationary across the insertion. The newly-inserted item appears above it.
- **Flag toggle on an item**: update/layout path triggers `snapToBounds` and `updateScroller`; the helper recomputes.
- **Multiple flagged items**: only the smallest-index materialized flagged node anchors. Others render normally.
- **`stackFromBottom` + `pinToEdgeWithInset` both active**: both mechanisms contribute to `effectiveInsets.top` via `max(…)`; the larger contribution wins. No coordination logic is added.
- **Flagged item outside recycling window**: helper returns 0 at the `lowestPinnedIndex != Int.max` guard; pinning re-engages when the node re-materializes.
- **items[0] outside recycling window**: helper returns 0 at the `sawIndexZero` guard. This state can only arise when content above the pinned item has already exceeded the available area (pushing leading items out of the recycling window), at which point pinning should be inert anyway — the guard makes that explicit and protects against under-counting heights.
- **Empty list**: no `itemNode` has an `index`; both loops complete with `lowestPinnedIndex == Int.max`; returns 0.
## Verification
No unit tests exist in the project (per CLAUDE.md). Verification path:
1. Full-project build:
```
source ~/.zshrc 2>/dev/null; \
PATH=/opt/homebrew/opt/ruby/bin:`gem environment gemdir`/bin:$PATH \
python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent \
--buildNumber 1 --configuration debug_sim_arm64
```
2. Manual exercise in a consumer that sets `pinToEdgeWithInset = true` on one item. Confirm: the flagged item sits at the bottom edge; inserting non-flagged items at index 0 keeps the flagged item visually anchored; once items above fill the available area, further scrolling is ordinary.
Because no existing item overrides `pinToEdgeWithInset` from its default `false`, the existing app surface is unaffected; any regression can only appear in a new consumer.
## Risk
The `effectiveInsets.top` contribution has to be computed identically at both call sites. Divergence (for example, `snapToBounds` adding the pin inset but `updateScroller` not) would cause the scroller's `contentSize` / `contentOffset` to disagree with the target scroll position produced by `snapToBounds`, producing scroll jumps. A shared helper — `calculatePinToEdgeTopInset` — and the identical diff applied at both sites is the defense against that.

237
docs/superpowers/specs/2026-04-18-postbox-to-telegramengine-wave-3-design.md
View file

@ -1,237 +0,0 @@
# Postbox → TelegramEngine refactor, Wave 3: MediaBox fetch/status/data facades + SaveToCameraRoll
**Date:** 2026-04-18
**Status:** Design approved; awaiting implementation plan.
**Predecessors:** Waves 1 and 2 (`docs/superpowers/specs/2026-04-16-postbox-to-telegramengine-refactor-wave-1-design.md`, `docs/superpowers/plans/2026-04-17-mediaresource-to-enginemediaresource-wave-2.md`).
## Goal
1. Unblock the full-module de-Postboxing of `submodules/SaveToCameraRoll` (abandoned in Wave 2) by adding engine-side facades for the `mediaBox` methods it uses.
2. Migrate `SaveToCameraRoll`'s three public functions to use those facades, drop `import Postbox` from the module, and update all call sites.
This wave follows the validated Wave-2 shape ("per-API migration, modify in place, update all call sites in one commit"), not the Wave-1 shape ("per-module Postbox drop").
## Non-goals
- Migrating any caller file (`InstantPageUI`, `BrowserUI`, `GalleryUI`, `ShareController`, `TelegramUI`, etc.) to drop its `import Postbox`. Each imports Postbox for many unrelated reasons; this wave only changes how they invoke `SaveToCameraRoll`.
- Adding facades for other `mediaBox` methods beyond the three SaveToCameraRoll needs (`cachedResourceRepresentation`, `completedResourcePath`, `storeResourceData`, etc.). Additive work belongs in future waves when a consumer needs them.
- Wrapping `FetchResourceSourceType` / `FetchResourceError` — these remain Postbox types, exposed by the `fetch` facade as a documented accepted leak. SaveToCameraRoll does not inspect these values.
- Adding `.incremental(waitUntilFetchStatus:)` to the `data` facade, or any of `range` / `statsCategory` / `reportResultStatus` / `preferBackgroundReferenceRevalidation` / `continueInBackground` to the `fetch` facade.
## Scope and inventory
### New engine surface
Three thin forwarding methods added to `TelegramEngine.Resources` in `submodules/TelegramCore/Sources/TelegramEngine/Resources/TelegramEngineResources.swift`. No new wrapper structs or classes.
```swift
public extension TelegramEngine {
final class Resources {
// ...existing methods...
public func fetch(
reference: MediaResourceReference,
userLocation: MediaResourceUserLocation,
userContentType: MediaResourceUserContentType
) -> Signal<FetchResourceSourceType, FetchResourceError> {
return fetchedMediaResource(
mediaBox: self.account.postbox.mediaBox,
userLocation: userLocation,
userContentType: userContentType,
reference: reference
)
}
public func status(
resource: EngineMediaResource
) -> Signal<EngineMediaResource.FetchStatus, NoError> {
return self.account.postbox.mediaBox.resourceStatus(resource._asResource())
|> map { EngineMediaResource.FetchStatus($0) }
}
public func data(
resource: EngineMediaResource,
pathExtension: String?,
waitUntilFetchStatus: Bool
) -> Signal<EngineMediaResource.ResourceData, NoError> {
return self.account.postbox.mediaBox.resourceData(
resource._asResource(),
pathExtension: pathExtension,
option: .complete(waitUntilFetchStatus: waitUntilFetchStatus)
)
|> map { EngineMediaResource.ResourceData($0) }
}
}
}
```
Design choices:
- **`data` takes a `waitUntilFetchStatus: Bool`**, not Postbox's `ResourceDataRequestOption` enum. SaveToCameraRoll only ever uses `.complete(waitUntilFetchStatus:)`. If a future consumer needs `.incremental(...)`, extend the facade at that point.
- **`fetch` takes only the 4 parameters SaveToCameraRoll uses.** `range`, `statsCategory`, `reportResultStatus`, `preferBackgroundReferenceRevalidation`, `continueInBackground` can be added additively when a consumer requires them.
- **`reference:` keeps the `MediaResourceReference` Postbox type.** Callers construct it inline via `mediaReference.resourceReference(resource)` and pass it without a local binding; no `import Postbox` is induced at the call site.
- **No wrapping of `FetchResourceSourceType` / `FetchResourceError`.** SaveToCameraRoll calls `.start()` on the `fetch` signal without inspecting the value; it does not import Postbox merely to use these types. Recorded here as an accepted leak.
### SaveToCameraRoll public API changes
The enum payload and three public function signatures change. Every caller breaks until updated.
Before:
```swift
public enum FetchMediaDataState {
case progress(Float)
case data(MediaResourceData)
}
public func fetchMediaData(
context: AccountContext, postbox: Postbox,
userLocation: MediaResourceUserLocation,
customUserContentType: MediaResourceUserContentType? = nil,
mediaReference: AnyMediaReference, forceVideo: Bool = false
) -> Signal<(FetchMediaDataState, Bool), NoError>
public func saveToCameraRoll(
context: AccountContext, postbox: Postbox,
userLocation: MediaResourceUserLocation,
customUserContentType: MediaResourceUserContentType? = nil,
mediaReference: AnyMediaReference, video: AnyMediaReference? = nil
) -> Signal<Float, NoError>
public func copyToPasteboard(
context: AccountContext, postbox: Postbox,
userLocation: MediaResourceUserLocation,
mediaReference: AnyMediaReference
) -> Signal<Void, NoError>
```
After:
```swift
public enum FetchMediaDataState {
case progress(Float)
case data(EngineMediaResource.ResourceData)
}
public func fetchMediaData(
context: AccountContext,
userLocation: MediaResourceUserLocation,
customUserContentType: MediaResourceUserContentType? = nil,
mediaReference: AnyMediaReference, forceVideo: Bool = false
) -> Signal<(FetchMediaDataState, Bool), NoError>
public func saveToCameraRoll(
context: AccountContext,
userLocation: MediaResourceUserLocation,
customUserContentType: MediaResourceUserContentType? = nil,
mediaReference: AnyMediaReference, video: AnyMediaReference? = nil
) -> Signal<Float, NoError>
public func copyToPasteboard(
context: AccountContext,
userLocation: MediaResourceUserLocation,
mediaReference: AnyMediaReference
) -> Signal<Void, NoError>
```
### SaveToCameraRoll internal changes
- `var resource: MediaResource?` → `var resource: TelegramMediaResource?` (TelegramCore protocol; matches CLAUDE.md cheat-sheet guidance). `representation.resource` and `file.resource` already return `TelegramMediaResource`, so no wrapping is needed at assignment.
- `fetchedMediaResource(mediaBox: postbox.mediaBox, …)` → `context.engine.resources.fetch(reference: mediaReference.resourceReference(resource), userLocation: userLocation, userContentType: userContentType)`.
- `postbox.mediaBox.resourceStatus(resource)` → `context.engine.resources.status(resource: EngineMediaResource(resource))`. The `switch status { case .Local … }` body is unchanged because `EngineMediaResource.FetchStatus` has the same cases (`.Local`, `.Remote(progress:)`, `.Fetching(isActive:progress:)`, `.Paused(progress:)`).
- `postbox.mediaBox.resourceData(resource, pathExtension: fileExtension, option: .complete(waitUntilFetchStatus: true))` → `context.engine.resources.data(resource: EngineMediaResource(resource), pathExtension: fileExtension, waitUntilFetchStatus: true)`.
- Local `MediaResourceData` bindings (`mainData: MediaResourceData?`, `videoData: MediaResourceData?`) and `case let .data(data):` destructurings → use `EngineMediaResource.ResourceData`.
- Field renames inside SaveToCameraRoll: `data.complete` → `data.isComplete`. `data.path` unchanged. `data.size` is not used internally.
- `import Postbox` removed from the file.
### Call-site migration (23 sites, 14 files)
Two mechanical edits per site.
Edit A — drop the `postbox:` argument:
```swift
// Before
saveToCameraRoll(context: context, postbox: context.account.postbox, userLocation: …, mediaReference: …)
// After
saveToCameraRoll(context: context, userLocation: …, mediaReference: …)
```
Edit B — update `FetchMediaDataState.data` field accesses at the ~7 sites that destructure `fetchMediaData` results:
- `data.complete` → `data.isComplete`
- `data.path` → unchanged
- `data.size` → `data.availableSize` (if used; likely not)
Inventory (captured 2026-04-18):
| Module | File | Calls |
|---|---|---|
| InstantPageUI | `Sources/InstantPageControllerNode.swift` | 2 |
| LegacyMediaPickerUI | `Sources/LegacyAttachmentMenu.swift` | 2 (destructures) |
| LegacyMediaPickerUI | `Sources/LegacyAvatarPicker.swift` | 2 (destructures) |
| BrowserUI | `Sources/BrowserInstantPageContent.swift` | 2 |
| GalleryUI | `Sources/Items/ChatImageGalleryItem.swift` | 2 (one destructures) |
| GalleryUI | `Sources/Items/UniversalVideoGalleryItem.swift` | 3 |
| TelegramUI (MediaEditorScreen) | `Components/MediaEditorScreen/Sources/MediaEditorScreen.swift` | 1 (destructures) |
| TelegramUI (MediaEditorScreen) | `Components/MediaEditorScreen/Sources/EditStories.swift` | 1 (destructures) |
| TelegramUI (ChatQrCodeScreen) | `Components/Chat/ChatQrCodeScreen/Sources/ChatQrCodeScreen.swift` | 1 (destructures) |
| TelegramUI (StoryContainer) | `Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerComponent.swift` | 1 |
| TelegramUI (PeerInfoStoryGrid) | `Components/PeerInfo/PeerInfoStoryGridScreen/Sources/PeerInfoStoryGridScreen.swift` | 1 |
| TelegramUI | `Sources/ChatInterfaceStateContextMenus.swift` | 1 |
| TelegramUI | `Sources/SaveMediaToFiles.swift` | 1 (destructures) |
| ShareController | `Sources/ShareController.swift` | 3 |
**Execution-time re-inventory:** before editing any code, the executor must re-grep for `fetchMediaData|saveToCameraRoll|copyToPasteboard` call sites across `submodules/`. If the count or file list drifts meaningfully from this table, abandon editing and revise the plan.
### Postbox-drop tally update
- `SaveToCameraRoll` joins the tally of modules free of `import Postbox`.
- No caller file is expected to drop `import Postbox` in this wave.
## Commit plan
Two commits, landing in order on `refactor/postbox-to-engine-wave-3`.
### C1 — `TelegramEngine.Resources: add fetch/status/data facades`
- Touches only `submodules/TelegramCore/Sources/TelegramEngine/Resources/TelegramEngineResources.swift`.
- Adds the three methods from the "New engine surface" section above. No behavior changes; no consumer changes.
- Buildable in isolation.
### C2 — `SaveToCameraRoll: drop import Postbox via engine.resources facades`
Atomic; must land as one commit because signature changes break every unmigrated caller.
- `submodules/SaveToCameraRoll/Sources/SaveToCameraRoll.swift`: public signature changes, `FetchMediaDataState.data` payload switch, internal rewrites, `import Postbox` removal.
- All 23 call sites in the inventory table updated in the same commit.
- ~7 destructuring sites also get the `data.complete` → `data.isComplete` rename.
## Build verification
Per CLAUDE.md, the only verification available is a full project build. No unit tests exist in the repo.
- After C1: full build.
- After C2: full build.
Both builds use the standard command from `CLAUDE.md` (Telegram build recipe with `--configuration debug_sim_arm64`), prefixed with `source ~/.zshrc 2>/dev/null;` to pick up `TELEGRAM_CODESIGNING_GIT_PASSWORD`.
## Risks and mitigations
- **New call site appears between planning and execution.** Mitigation: re-grep at execution time before editing; abandon & revise if count drifts meaningfully.
- **`FetchResourceSourceType` / `FetchResourceError` are Postbox types.** Mitigation: SaveToCameraRoll never inspects these; future consumers that need to pattern-match will wrap these types in a later wave.
- **A consumer turns out to need a mediaBox facade not in this spec** (e.g., `cachedResourceRepresentation`). Mitigation: out of scope. Abandon that caller's migration; the facade commit still stands on its own.
- **`context.engine` unavailable at some call site.** Risk minimal: `AccountContext.engine` is a protocol requirement in `submodules/AccountContext/Sources/AccountContext.swift`, so it is universally available at any site that already has `context: AccountContext`. All 23 sites match.
- **ShareController:2406 uses a non-`context.account.postbox` Postbox.** At `submodules/ShareController/Sources/ShareController.swift:2406`, the call reads `let postbox = self.currentContext.stateManager.postbox` and passes that as `postbox:`. After migration, SaveToCameraRoll internally uses `context.account.postbox.mediaBox` via the engine. In the gated `ShareControllerAppAccountContext` path, `accountContext.context.account.stateManager` should match `self.currentContext.stateManager`, so the two postboxes are equivalent; verify this at execution time before editing. If they can diverge (e.g., during share-extension account switching), this specific call site must be abandoned with a recorded reason — the rest of the wave is unaffected.
- **Umbrella-type rule-2 compliance.** No `Postbox` / `Account` / `MediaBox` typealias is added. No new wrapper struct is introduced. ✅
## Abandonment criteria
If any call site cannot be migrated mechanically — for example, it passes a non-`context.account.postbox` custom `Postbox`, or constructs a `MediaResourceReference` in a way that forces a retained `import Postbox` in a file the wave intends to de-Postbox — abandon that specific call site with a recorded reason in the plan. The facade commit (C1) still stands on its own; SaveToCameraRoll's internal migration still lands if at least the other callers migrate. If too many call sites abandon, abandon the whole wave and record lessons.
## Expected outcome
- `TelegramEngine.Resources` has three new thin forwarders.
- `SaveToCameraRoll` no longer imports Postbox.
- Running tally of Postbox-free consumer modules: Wave 1 cohort + `StickerPeekUI`, `PromptUI`, `PresentationDataUtils` (standalone) + `MapResourceToAvatarSizes` (Wave 2) + **`SaveToCameraRoll` (Wave 3)**.
- Zero behavior change.

204
docs/superpowers/specs/2026-04-18-postbox-to-telegramengine-wave-4-design.md
View file

@ -1,204 +0,0 @@
# Postbox → TelegramEngine refactor, Wave 4: `TelegramEngine.Stickers.uploadSticker` facade migration
**Date:** 2026-04-18
**Status:** Design approved; awaiting implementation plan.
**Predecessors:** Waves 1–3.
- `docs/superpowers/specs/2026-04-16-postbox-to-telegramengine-refactor-wave-1-design.md`
- `docs/superpowers/plans/2026-04-17-mediaresource-to-enginemediaresource-wave-2.md`
- `docs/superpowers/specs/2026-04-18-postbox-to-telegramengine-wave-3-design.md`
## Goal
Migrate the public facade `TelegramEngine.Stickers.uploadSticker` so its signature and its return-enum payload no longer leak Postbox-domain types:
- `peer: Peer → EnginePeer`
- `resource: MediaResource → EngineMediaResource`
- `thumbnail: MediaResource? → EngineMediaResource?`
- `UploadStickerStatus.complete(CloudDocumentMediaResource, String) → .complete(EngineMediaResource, String)`
Follows the validated Wave-2 shape ("per-facade-API migration, modify in place, update call sites in the same commit").
## Non-goals
- Migrating the caller files (`ImportStickerPackUI/Sources/ImportStickerPackController.swift`, `TelegramUI/Components/MediaEditorScreen/Sources/MediaEditorScreen.swift`) to drop `import Postbox`. Each imports Postbox for unrelated reasons; this wave only changes how they invoke `uploadSticker`.
- Migrating other `TelegramEngine.Stickers` facades (e.g. `createStickerSet`, `addStickerToStickerSet`) that have similar Peer/MediaResource leaks. Future-wave work.
- Wrapping or renaming `CloudDocumentMediaResource` itself (it's a TelegramCore-defined class conforming to the `TelegramMediaResource` protocol). It stays usable internally; this wave just stops exposing it in the public enum payload.
- Changes to `_internal_uploadSticker`'s signature. It continues to take raw `Peer` and `MediaResource`, consistent with CLAUDE.md's "internal Postbox-facing layer stays raw" rule — with one intentional one-line exception documented below.
## Scope
### Core change: `UploadStickerStatus` enum
In `submodules/TelegramCore/Sources/TelegramEngine/Stickers/ImportStickers.swift`:
```swift
// Before (line 7-10)
public enum UploadStickerStatus {
case progress(Float)
case complete(CloudDocumentMediaResource, String)
}
// After
public enum UploadStickerStatus {
case progress(Float)
case complete(EngineMediaResource, String)
}
```
`UploadStickerStatus` is both the public return type of the facade and the return type of `_internal_uploadSticker`. Rather than split it into two enums (one raw for the internal layer, one engine-wrapped for the public facade), this wave keeps one enum and wraps at the single `.complete(...)` construction site inside `_internal_uploadSticker` (line ~97 of the same file):
```swift
// Before
return .single(.complete(uploadedResource, file.mimeType))
// After
return .single(.complete(EngineMediaResource(uploadedResource), file.mimeType))
```
**This one-line construction of `EngineMediaResource` inside `_internal_uploadSticker` is a narrow, spec-allowed exception** to CLAUDE.md's "internal Postbox-facing stays raw" guideline. The alternative (splitting the enum) fragments a simple public surface and duplicates bookkeeping. `EngineMediaResource` is defined in `TelegramCore` and already accessible without additional imports.
### Facade signature migration
In `submodules/TelegramCore/Sources/TelegramEngine/Stickers/TelegramEngineStickers.swift`:
```swift
// Before (line 85-87)
public func uploadSticker(peer: Peer, resource: MediaResource, thumbnail: MediaResource?, alt: String, dimensions: PixelDimensions, duration: Double?, mimeType: String) -> Signal<UploadStickerStatus, UploadStickerError> {
return _internal_uploadSticker(account: self.account, peer: peer, resource: resource, thumbnail: thumbnail, alt: alt, dimensions: dimensions, duration: duration, mimeType: mimeType)
}
// After
public func uploadSticker(peer: EnginePeer, resource: EngineMediaResource, thumbnail: EngineMediaResource?, alt: String, dimensions: PixelDimensions, duration: Double?, mimeType: String) -> Signal<UploadStickerStatus, UploadStickerError> {
return _internal_uploadSticker(account: self.account, peer: peer._asPeer(), resource: resource._asResource(), thumbnail: thumbnail?._asResource(), alt: alt, dimensions: dimensions, duration: duration, mimeType: mimeType)
}
```
The facade bridges all three type swaps (`peer._asPeer()`, `resource._asResource()`, `thumbnail?._asResource()`). `_internal_uploadSticker`'s own signature does not change.
### Call-site migration (2 sites, 2 files)
**1. `submodules/ImportStickerPackUI/Sources/ImportStickerPackController.swift:91`** — argument simplification and destructure simplification:
```swift
// Before
signals.append(strongSelf.context.engine.stickers.uploadSticker(peer: peer, resource: resource._asResource(), thumbnail: nil, alt: sticker.emojis.first ?? "", dimensions: PixelDimensions(width: 512, height: 512), duration: nil, mimeType: sticker.mimeType)
|> map { result -> (UUID, StickerVerificationStatus, EngineMediaResource?) in
switch result {
case .progress:
return (sticker.uuid, .loading, nil)
case let .complete(resource, mimeType):
if ["application/x-tgsticker", "video/webm"].contains(mimeType) {
return (sticker.uuid, .verified, EngineMediaResource(resource))
} else {
return (sticker.uuid, .declined, nil)
}
}
}
```
becomes:
```swift
signals.append(strongSelf.context.engine.stickers.uploadSticker(peer: peer, resource: resource, thumbnail: nil, alt: sticker.emojis.first ?? "", dimensions: PixelDimensions(width: 512, height: 512), duration: nil, mimeType: sticker.mimeType)
|> map { result -> (UUID, StickerVerificationStatus, EngineMediaResource?) in
switch result {
case .progress:
return (sticker.uuid, .loading, nil)
case let .complete(resource, mimeType):
if ["application/x-tgsticker", "video/webm"].contains(mimeType) {
return (sticker.uuid, .verified, resource)
} else {
return (sticker.uuid, .declined, nil)
}
}
}
```
Three changes:
- `peer` in this enclosing closure is a raw `Peer` (from `postbox.loadedPeerWithId(...)`, whose signature is `Signal<Peer, NoError>`). Currently the facade takes `Peer` so the identifier is passed as-is. After the facade moves to `EnginePeer`, wrap at the call: `peer: EnginePeer(peer)`.
- `resource._asResource()` → `resource` (the local `resource` is already `EngineMediaResource`).
- `EngineMediaResource(resource)` → `resource` in the destructure (the destructured `resource` is now `EngineMediaResource` directly).
**2. `submodules/TelegramUI/Components/MediaEditorScreen/Sources/MediaEditorScreen.swift:8099`** — unwrap removed, wraps added:
```swift
// Before
return context.engine.stickers.uploadSticker(peer: peer._asPeer(), resource: resource, thumbnail: file.previewRepresentations.first?.resource, alt: "", dimensions: dimensions, duration: duration, mimeType: mimeType)
// After
return context.engine.stickers.uploadSticker(peer: peer, resource: EngineMediaResource(resource), thumbnail: file.previewRepresentations.first.flatMap { EngineMediaResource($0.resource) }, alt: "", dimensions: dimensions, duration: duration, mimeType: mimeType)
```
The enclosing block is a nested `mapToSignal` chain starting at line ~8084. The `UploadStickerStatus` payload migration cascades through several lines in this block:
- **Line 8097** — `.complete(resource, mimeType)` where `resource` was narrowed via `if let resource = resource as? CloudDocumentMediaResource`. After the payload migration this `.complete(...)` constructor takes `EngineMediaResource`, so wrap: `.complete(EngineMediaResource(resource), mimeType)`.
- **Line 8099** — the main facade call. `peer._asPeer()` → `peer` (the local `peer` is an `EnginePeer`, confirmed by the current `_asPeer()`); `resource` → `EngineMediaResource(resource)` (the local `resource` here is a raw `MediaResource` from the outer enum's `.complete(resource)` case); `file.previewRepresentations.first?.resource` → `file.previewRepresentations.first.flatMap { EngineMediaResource($0.resource) }`.
- **Line 8105** — `case let .complete(resource, _):` destructures the inner `UploadStickerStatus`. After migration, `resource` has type `EngineMediaResource`.
- **Line 8106** — `stickerFile(resource: resource, thumbnailResource: file.previewRepresentations.first?.resource, …)` — `stickerFile` is declared with `resource: TelegramMediaResource, thumbnailResource: TelegramMediaResource?, …`, so unwrap: `stickerFile(resource: resource._asResource(), thumbnailResource: file.previewRepresentations.first?.resource, …)`. The `thumbnailResource` argument is already a `TelegramMediaResource?` and needs no change.
- **Line 8119** — `ImportSticker(resource: .standalone(resource: resource), …)`. `MediaResourceReference.standalone(resource:)` takes `MediaResource`, so unwrap: `.standalone(resource: resource._asResource())`.
- **Line 8138** — same as 8119 inside the `.addToStickerPack` case.
- **Line 8178** — outer-handler destructure `case let .complete(resource, _):`. After migration, `resource` is `EngineMediaResource`.
- **Line 8180** — `stickerFile(resource: resource, thumbnailResource: file.previewRepresentations.first?.resource, size: resource.size ?? 0, …)`. Two unwrap sites here: `resource: resource._asResource()` for the first argument, and `size: resource._asResource().size ?? 0` for the size read (`EngineMediaResource` does not expose `.size`; only `MediaResource` does). Introduce a local `let rawResource = resource._asResource()` at the top of the `case` to avoid calling `_asResource()` twice.
**Execution-time check:** before editing MediaEditorScreen, re-read the full block (roughly lines 8080–8190) and the `stickerFile` function signature (line 9196) to confirm these assumptions. If any additional downstream use of the destructured `resource` appears that wasn't caught above, decide inline whether it needs `._asResource()` or can take `EngineMediaResource` directly.
## Execution-time re-inventory
Before editing, re-grep to catch any new call sites:
```bash
grep -rnE "\.uploadSticker\(" submodules --include="*.swift" | grep -v "/TelegramEngine/Stickers/"
```
Expected output lines that pattern-match the facade (not the `MediaEditorScreen`'s private `self.uploadSticker(file, action:)` helper):
- `submodules/ImportStickerPackUI/Sources/ImportStickerPackController.swift:91`
- `submodules/TelegramUI/Components/MediaEditorScreen/Sources/MediaEditorScreen.swift:8099`
Other `self.uploadSticker(...)` lines in `MediaEditorScreen.swift` (7771, 7808, 7852, 7896, 7913, 7931, 8019) are calls to a private helper method, not the engine facade — leave those untouched.
If the facade call-site count drifts beyond these two, stop and revise the plan.
## Commit plan
One atomic commit covering all four files:
**C1 — `TelegramEngine.Stickers.uploadSticker: migrate to EnginePeer + EngineMediaResource`**
- `submodules/TelegramCore/Sources/TelegramEngine/Stickers/ImportStickers.swift` — enum payload + one `.complete(...)` construction site.
- `submodules/TelegramCore/Sources/TelegramEngine/Stickers/TelegramEngineStickers.swift` — facade signature.
- `submodules/ImportStickerPackUI/Sources/ImportStickerPackController.swift` — 1 call site + destructure.
- `submodules/TelegramUI/Components/MediaEditorScreen/Sources/MediaEditorScreen.swift` — 1 call site.
Atomicity is required because the enum payload change, facade signature change, and call-site changes are all mutually breaking.
**C2 — `CLAUDE.md: record wave-4 outcome`**
- Add a "Wave 4 outcome (2026-04-18)" subsection documenting the facade migrated.
- Remove the `uploadSticker` bullet from "Known future-wave candidates".
- No change to the "Modules currently free of `import Postbox`" running tally (no module is de-Postboxed in this wave).
## Build verification
One full project build after the edits, before committing C1. The bazel command from CLAUDE.md, prefixed with `source ~/.zshrc 2>/dev/null;` to pick up `TELEGRAM_CODESIGNING_GIT_PASSWORD`.
## Risks and mitigations
- **Risk:** a new call site of `engine.stickers.uploadSticker` appears between planning and execution. **Mitigation:** the re-grep above catches this; abandon or extend the plan if so.
- **Risk:** `UploadStickerStatus.complete` is destructured somewhere that accesses `CloudDocumentMediaResource`-specific members. **Mitigation:** grep confirms both known sites use the value generically (wrap or assign directly); no `.stringRepresentation`-style `CloudDocumentMediaResource`-specific access is expected. If found, abandon the wave.
- **Risk:** `MediaEditorScreen:8099`'s `resource` local is already an `EngineMediaResource`. **Mitigation:** inspect the enclosing function at execution time and adjust the wrap accordingly.
- **Risk:** the one-line `EngineMediaResource(uploadedResource)` wrap inside `_internal_uploadSticker` is a narrow deviation from "Postbox-facing layer stays raw". **Mitigation:** spec explicitly calls this out. The alternative (splitting the enum) is worse for a single-line gain; documented and accepted.
- **Rule-2 compliance:** no `Postbox`/`Account`/`MediaBox` typealias introduced; no new wrapper struct. ✅
## Abandonment criteria
If any call-site edit turns out to require a cascading type change elsewhere (e.g. a struct field or signature typed as `CloudDocumentMediaResource`), abandon the wave and record the reason. The single-commit shape means either the whole thing lands or none of it does.
## Expected outcome
- `TelegramEngine.Stickers.uploadSticker`'s public surface no longer references `Peer`, `MediaResource`, or `CloudDocumentMediaResource`.
- `UploadStickerStatus.complete`'s payload becomes `(EngineMediaResource, String)`.
- `_internal_uploadSticker`'s signature stays as-is (raw `Peer`/`MediaResource`), with one inline `EngineMediaResource(uploadedResource)` wrap at the result-construction site.
- Two call sites updated; no caller module becomes Postbox-free.
- CLAUDE.md records the outcome and removes the `uploadSticker` entry from "Known future-wave candidates".
- Zero behavior change.

270
docs/superpowers/specs/2026-04-18-postbox-to-telegramengine-wave-5-design.md
View file

@ -1,270 +0,0 @@
# Postbox → TelegramEngine refactor, Wave 5: `uploadSecureIdFile` facade + SecureId context migration
**Date:** 2026-04-18
**Status:** Design approved; awaiting implementation plan.
**Predecessors:** Waves 1–4.
## Goal
Complete the last explicitly-named future-wave candidate from CLAUDE.md: migrate `uploadSecureIdFile`'s public surface to stop leaking the `Postbox`/`Network`/`MediaResource` Postbox-domain types, and refactor its caller `SecureIdVerificationDocumentsContext` so the caller stops importing Postbox.
- `uploadSecureIdFile(context: SecureIdAccessContext, postbox: Postbox, network: Network, resource: MediaResource)` → `(context:, engine: TelegramEngine, resource: EngineMediaResource)`.
- `SecureIdVerificationDocumentsContext` drops its `postbox: Postbox` + `network: Network` stored properties, takes `engine: TelegramEngine` instead, and drops `import Postbox` from the file.
- The one instantiation site updates to pass `engine: self.context.engine`.
## Non-goals
- Migrating `SecureIdAccessContext`, `SecureIdVerificationDocument`, `SecureIdVerificationLocalDocument`, or other SecureId-domain types. They live in TelegramCore (not Postbox) already and do not leak.
- Migrating other SecureId-family functions in TelegramCore (e.g., `_internal_requestSecureIdVerification`, etc.). Future-wave work.
- Dropping `import Postbox` from `SecureIdDocumentFormControllerNode.swift`. That file imports Postbox for unrelated reasons.
## Scope and inventory
### Files touched (3 in the code commit)
1. `submodules/TelegramCore/Sources/TelegramEngine/SecureId/UploadSecureIdFile.swift` — facade signature change, 3-line body bridge.
2. `submodules/PassportUI/Sources/SecureIdVerificationDocumentsContext.swift` — stored props, constructor, internal call, drop `import Postbox`.
3. `submodules/PassportUI/Sources/SecureIdDocumentFormControllerNode.swift` — one-line instantiation call.
### Facade signature migration (`UploadSecureIdFile.swift`)
Before:
```swift
public func uploadSecureIdFile(context: SecureIdAccessContext, postbox: Postbox, network: Network, resource: MediaResource) -> Signal<UploadSecureIdFileResult, UploadSecureIdFileError> {
return postbox.mediaBox.resourceData(resource)
|> mapError { _ -> UploadSecureIdFileError in
}
|> mapToSignal { next -> Signal<UploadSecureIdFileResult, UploadSecureIdFileError> in
if !next.complete {
return .complete()
}
guard let data = try? Data(contentsOf: URL(fileURLWithPath: next.path)) else {
return .fail(.generic)
}
guard let encryptedData = encryptedSecureIdFile(context: context, data: data) else {
return .fail(.generic)
}
return multipartUpload(network: network, postbox: postbox, source: .data(encryptedData.data), encrypt: false, tag: TelegramMediaResourceFetchTag(statsCategory: .image, userContentType: .image), hintFileSize: nil, hintFileIsLarge: false, forceNoBigParts: false)
|> mapError { _ -> UploadSecureIdFileError in
return .generic
}
|> mapToSignal { result -> Signal<UploadSecureIdFileResult, UploadSecureIdFileError> in
switch result {
case let .progress(value):
return .single(.progress(value))
case let .inputFile(.inputFile(fileData)):
return .single(.result(UploadedSecureIdFile(id: fileData.id, parts: fileData.parts, md5Checksum: fileData.md5Checksum, fileHash: encryptedData.hash, encryptedSecret: encryptedData.encryptedSecret), encryptedData.data))
default:
return .fail(.generic)
}
}
}
}
```
After:
```swift
public func uploadSecureIdFile(context: SecureIdAccessContext, engine: TelegramEngine, resource: EngineMediaResource) -> Signal<UploadSecureIdFileResult, UploadSecureIdFileError> {
return engine.account.postbox.mediaBox.resourceData(resource._asResource())
|> mapError { _ -> UploadSecureIdFileError in
}
|> mapToSignal { next -> Signal<UploadSecureIdFileResult, UploadSecureIdFileError> in
if !next.complete {
return .complete()
}
guard let data = try? Data(contentsOf: URL(fileURLWithPath: next.path)) else {
return .fail(.generic)
}
guard let encryptedData = encryptedSecureIdFile(context: context, data: data) else {
return .fail(.generic)
}
return multipartUpload(network: engine.account.network, postbox: engine.account.postbox, source: .data(encryptedData.data), encrypt: false, tag: TelegramMediaResourceFetchTag(statsCategory: .image, userContentType: .image), hintFileSize: nil, hintFileIsLarge: false, forceNoBigParts: false)
|> mapError { _ -> UploadSecureIdFileError in
return .generic
}
|> mapToSignal { result -> Signal<UploadSecureIdFileResult, UploadSecureIdFileError> in
switch result {
case let .progress(value):
return .single(.progress(value))
case let .inputFile(.inputFile(fileData)):
return .single(.result(UploadedSecureIdFile(id: fileData.id, parts: fileData.parts, md5Checksum: fileData.md5Checksum, fileHash: encryptedData.hash, encryptedSecret: encryptedData.encryptedSecret), encryptedData.data))
default:
return .fail(.generic)
}
}
}
}
```
Three substantive body changes, all in line with the CLAUDE.md rule that "internal Postbox-facing stays raw" — the body is inside TelegramCore itself so it accesses raw Postbox types through `engine.account.postbox` without going through the wave-3 facades:
- `postbox.mediaBox.resourceData(resource)` → `engine.account.postbox.mediaBox.resourceData(resource._asResource())` (unwrap the engine resource before handing to raw MediaBox).
- `network: network` → `network: engine.account.network`.
- `postbox: postbox` → `postbox: engine.account.postbox`.
The `_internal_*` convention does not apply here because `uploadSecureIdFile` is itself the facade — there is no separate raw-typed `_internal_uploadSecureIdFile` helper, and this wave does not introduce one. The function continues to have a single definition serving both internal TelegramCore wiring and consumer use.
### Caller-class migration (`SecureIdVerificationDocumentsContext.swift`)
Before:
```swift
import Foundation
import Postbox
import TelegramCore
import SwiftSignalKit
private final class DocumentContext {
private let disposable: Disposable
init(disposable: Disposable) {
self.disposable = disposable
}
deinit {
self.disposable.dispose()
}
}
final class SecureIdVerificationDocumentsContext {
private let context: SecureIdAccessContext
private let postbox: Postbox
private let network: Network
private let update: (Int64, SecureIdVerificationLocalDocumentState) -> Void
private var contexts: [Int64: DocumentContext] = [:]
private(set) var uploadedFiles: [Data: Data] = [:]
init(postbox: Postbox, network: Network, context: SecureIdAccessContext, update: @escaping (Int64, SecureIdVerificationLocalDocumentState) -> Void) {
self.postbox = postbox
self.network = network
self.context = context
self.update = update
}
func stateUpdated(_ documents: [SecureIdVerificationDocument]) {
// ...
disposable.set((uploadSecureIdFile(context: self.context, postbox: self.postbox, network: self.network, resource: info.resource)
// ...
}
}
```
After:
```swift
import Foundation
import TelegramCore
import SwiftSignalKit
private final class DocumentContext {
private let disposable: Disposable
init(disposable: Disposable) {
self.disposable = disposable
}
deinit {
self.disposable.dispose()
}
}
final class SecureIdVerificationDocumentsContext {
private let context: SecureIdAccessContext
private let engine: TelegramEngine
private let update: (Int64, SecureIdVerificationLocalDocumentState) -> Void
private var contexts: [Int64: DocumentContext] = [:]
private(set) var uploadedFiles: [Data: Data] = [:]
init(engine: TelegramEngine, context: SecureIdAccessContext, update: @escaping (Int64, SecureIdVerificationLocalDocumentState) -> Void) {
self.engine = engine
self.context = context
self.update = update
}
func stateUpdated(_ documents: [SecureIdVerificationDocument]) {
// ...
disposable.set((uploadSecureIdFile(context: self.context, engine: self.engine, resource: EngineMediaResource(info.resource))
// ...
}
}
```
Changes:
1. Drop `import Postbox` (line 2).
2. Replace `private let postbox: Postbox` and `private let network: Network` with `private let engine: TelegramEngine`.
3. Constructor: `postbox:, network:, context:, update:` → `engine:, context:, update:`.
4. Constructor body: `self.postbox = postbox; self.network = network` → `self.engine = engine`.
5. Inside `stateUpdated`: `postbox: self.postbox, network: self.network` → `engine: self.engine`; `resource: info.resource` → `resource: EngineMediaResource(info.resource)` (wrap; `info.resource` is `TelegramMediaResource` per `SecureIdVerificationLocalDocument` definition).
`DocumentContext` inner class is untouched. Other methods in the file are untouched.
### Instantiation-site edit (`SecureIdDocumentFormControllerNode.swift`)
Single line, [line 2172](submodules/PassportUI/Sources/SecureIdDocumentFormControllerNode.swift#L2172):
```swift
// Before
self.uploadContext = SecureIdVerificationDocumentsContext(postbox: self.context.account.postbox, network: self.context.account.network, context: self.secureIdContext, update: { id, state in
// After
self.uploadContext = SecureIdVerificationDocumentsContext(engine: self.context.engine, context: self.secureIdContext, update: { id, state in
```
`self.context` is the outer `AccountContext`. `self.context.engine` is the `TelegramEngine` (universally available via the `AccountContext` protocol). `self.secureIdContext` is the unrelated inner `SecureIdAccessContext` — kept as the `context:` argument.
## Execution-time re-inventory
Before editing, re-grep to catch any new call sites:
```bash
grep -rnE "uploadSecureIdFile\(" submodules --include="*.swift" | grep -v "/SecureId/"
grep -rnE "SecureIdVerificationDocumentsContext\(" submodules --include="*.swift" | grep -v "final class SecureIdVerificationDocumentsContext"
```
Expected: exactly 1 match for each — `SecureIdVerificationDocumentsContext.swift:43` and `SecureIdDocumentFormControllerNode.swift:2172` respectively. If either count has drifted, stop and revise the plan.
## Commit plan
**C1 — `SecureId: migrate uploadSecureIdFile + context to TelegramEngine`** (atomic)
- All three files listed above, landing together.
**C2 — `CLAUDE.md: record wave-5 outcome`**
- Add `SecureIdVerificationDocumentsContext` to the "Modules currently free of `import Postbox`" running tally.
- Add a "Wave 5 outcome (2026-04-18)" subsection describing the migration.
- Remove the `uploadSecureIdFile` bullet from "Known future-wave candidates". After this, only the 4 permanently-blocked classes remain.
## Build verification
One full project build after C1's edits, before committing. Bazel command from CLAUDE.md with `source ~/.zshrc 2>/dev/null;` prefix.
## Risks and mitigations
- **Risk:** an additional call site of `uploadSecureIdFile` appears between planning and execution. **Mitigation:** the execution-time re-grep catches this. Expected 1 match.
- **Risk:** `SecureIdDocumentFormControllerNode.swift`'s `self.context` isn't an `AccountContext` at the instantiation site. **Mitigation:** confirm at execution time. The `AccountContext` protocol mandates `var engine: TelegramEngine { get }`, so any concrete `AccountContext` has it.
- **Risk:** behavior regression from `multipartUpload(network: engine.account.network, postbox: engine.account.postbox, …)`. **Mitigation:** these are the same underlying instances as the pre-migration `self.network` / `self.postbox` values (both originate from `self.context.account.network` / `.postbox`). Zero behavior change.
- **Risk:** after `import Postbox` is dropped from `SecureIdVerificationDocumentsContext.swift`, an implicit `Network` type (used elsewhere in the file?) fails to resolve. **Mitigation:** the file's only `Network` usage is in the stored `private let network` and the constructor parameter — both removed. No other `Network` reference survives.
- **Rule-2 compliance:** no `Postbox`/`Account`/`MediaBox` typealias introduced. No new wrapper struct. The facade body's `engine.account.postbox.mediaBox` and `engine.account.network` are internal expressions inside TelegramCore (not public surface). ✅
## Abandonment criteria
If any of the 3 files cannot be migrated mechanically (e.g. `SecureIdDocumentFormControllerNode.swift`'s enclosing class doesn't have an `AccountContext`), abandon the wave and record the reason. The one-commit atomic shape means either the whole thing lands or none of it does.
## Expected outcome
- `uploadSecureIdFile`'s public signature references neither `Postbox` nor `Network` nor `MediaResource`.
- `SecureIdVerificationDocumentsContext` no longer imports Postbox and joins the Postbox-free running tally.
- `SecureIdDocumentFormControllerNode.swift` continues to import Postbox for unrelated reasons (no tally impact).
- `uploadSecureIdFile` bullet is removed from CLAUDE.md's "Known future-wave candidates"; after this wave, only the 4 permanently-blocked `TelegramMediaResource`-conforming classes remain in the candidate list.
- Full build succeeds in `debug_sim_arm64`.
- Zero behavior change.

134
docs/superpowers/specs/2026-04-19-postbox-to-telegramengine-wave-6-design.md
View file

@ -1,134 +0,0 @@
# Postbox → TelegramEngine refactor, Wave 6: unused `import Postbox` batch sweep
**Date:** 2026-04-19
**Status:** Design approved; awaiting implementation plan.
**Predecessors:** Waves 1–5.
## Goal
Clear `import Postbox` lines that have become unused across consumer submodules. Previous waves migrated facades and caller-side usages; in many files the last semantic use of a Postbox type was removed but the `import Postbox` line remained. This wave identifies and removes all such dangling imports in a single build-verified commit.
Unlike waves 1–5, this is not a per-facade or per-module migration. It's a large-blast-radius, zero-semantic-change sweep where the project build is the safety net: anything that compiles is definitionally safe to drop.
## Non-goals
- Migrating any facade API or adding typealiases, wrappers, or `engine` plumbing. Pure deletion.
- Touching files inside `submodules/TelegramCore/`, `submodules/Postbox/`, or `submodules/TelegramApi/`. Their `import Postbox` lines are structural, not cleanup-eligible.
- Dropping `import Postbox` from files whose Postbox uses are indirect but real (`Media`, `ItemCollectionId`, `Peer` as a protocol not yet typealiased, etc.). The build tells us which these are.
- Dropping any other unused imports (Foundation, UIKit, etc.). Postbox only.
- Resolving or editing `@_exported import Postbox` lines. Only the plain `import Postbox` on its own line is in scope.
## Scope
### Candidate discovery
Candidate list is generated by:
```bash
grep -rl "^import Postbox$" submodules --include="*.swift" \
| grep -vE "/(TelegramCore|Postbox|TelegramApi)/"
```
Expected candidate count: on the order of 200–300 files. Only a fraction are actually unused imports; the rest need their `import Postbox` restored after speculative drop.
### Methodology: speculative-drop + build-verify
1. **Snapshot** every candidate file's current content. Any of the following is acceptable:
- Copy files to a temp directory keyed by relative path.
- Record the candidate file list plus a single `git stash --keep-index` that captures the pre-edit state.
- Simply rely on `git checkout -- <file>` to restore, since every snapshot is the committed state at branch HEAD before the wave.
The last option is simplest and chosen for this wave.
2. **Speculative drop:** remove the `import Postbox` line from every candidate. Exact edit: delete the full line matching `^import Postbox$` (not `@_exported import Postbox`, not `import Postbox // comment` — the plain form only).
3. **Full build.** Expect some compile errors — these identify files that actually need the import.
4. **Parse errors.** Each Swift compile error begins with `<file>:<line>:<col>: error:`. Collect the set of unique files that have any error. Each of these gets `import Postbox` restored via `git checkout -- <file>`.
5. **Rebuild.** Goal: clean success.
6. **Iterate.** If new errors surface (rare — should only happen when a symbol was exported transitively), restore those files too. Hard cap: 3 iterations. If iteration 3 still fails, abandon and revert the whole wave.
7. **Stage and commit** all surviving per-file diffs (each will be a single-line deletion) as one atomic C1 commit.
### Error-parsing discipline
Only restore a file for one of these error categories:
- `cannot find type 'X' in scope` where `X` is a Postbox-exported symbol.
- `use of unresolved identifier 'X'` where `X` is a Postbox-exported symbol.
- `cannot find 'X' in scope` for Postbox symbols.
- `no such module 'Postbox'` — shouldn't occur unless Bazel deps are broken; if it does, halt and investigate.
Do NOT restore imports for:
- Codesign / dependency-graph failures unrelated to Swift compilation.
- Errors in files that weren't among the candidate set (those indicate cascading breakage — halt and investigate).
- Warnings about unused imports (those are the OPPOSITE signal — keep the drop).
### Automation
Because the candidate set is large (~200+ files), manual editing is impractical. Use a short helper script (plain bash + `sed`) to:
1. Write the candidate list to `/tmp/wave-6-candidates.txt`.
2. Run `sed -i '' '/^import Postbox$/d' <file>` for each candidate.
3. Run the full build, capturing stderr.
4. Extract file paths from error lines.
5. `git checkout --` those files.
6. Rebuild, extract more error paths, repeat.
Script-wise it's 20–30 lines of bash. The plan will include the exact commands.
### Out-of-scope files
- `submodules/TelegramCore/` — never touched.
- `submodules/Postbox/` — never touched.
- `submodules/TelegramApi/` — never touched.
- Files with `@_exported import Postbox` — never touched (but the regex `^import Postbox$` would not match them anyway).
## Commit plan
**C1 — `Drop unused import Postbox from N consumer files`** (atomic, one commit, build-verified)
- All surviving per-file deletions. Each file's only change is a single-line deletion.
- Commit message notes the count (N) and confirms the build-verified methodology.
**C2 — `CLAUDE.md: record wave-6 outcome and unused-import-sweep methodology`**
- New "Wave 6 outcome (2026-04-19)" subsection.
- **New permanent guidance subsection** added under "Wave-selection guidance" (not tied to wave 6's specific results), capturing the methodology for future re-runs. Text along the lines of:
> **Unused-import sweeps are a valid wave shape.** After a round of facade migrations, consumer files accumulate `import Postbox` lines whose last semantic use was removed. Periodically sweep these:
>
> 1. `grep -rl "^import Postbox$" submodules --include="*.swift" | grep -vE "/(TelegramCore|Postbox|TelegramApi)/"` to generate candidates.
> 2. `sed -i '' '/^import Postbox$/d' <file>` to speculatively drop the import from all candidates.
> 3. Run a full project build. Parse `<file>:<line>:<col>: error:` lines to identify files that need the import restored. Restore via `git checkout -- <file>`.
> 4. Rebuild. Iterate up to 3 times.
> 5. Commit surviving drops as one atomic commit.
>
> Re-run after every 2–3 facade-migration waves to convert accumulated cleanup into tally wins.
- **Running tally update:** add to the "Modules currently free of `import Postbox`" list any module where, after the sweep, no file contains `import Postbox`. Module-level inclusion is stricter than per-file cleanup — only counts when ALL Swift files in a module are clean.
## Build verification
- Iteration 1: full build with all candidates dropped. Expect errors.
- Iteration 2 (and optionally 3): full build with failed files restored.
- Final iteration: clean build, required before commit.
Use the standard CLAUDE.md build command, prefixed with `source ~/.zshrc 2>/dev/null;`.
## Risks and mitigations
- **Very long candidate list causes a very long first build iteration.** Bazel will recompile any module whose sources changed, plus downstream dependents. Nearly every consumer module is dropping at least one file's import, so the first build touches most modules. Mitigation: accept the cost; subsequent iterations only touch files where errors surfaced — far fewer recompilations. Total: expect 2 full project rebuilds.
- **Error cascading: a single missing import in an upstream module breaks many downstream files.** Restoring the upstream file's import may silence a large batch of errors at once. Mitigation: restore one pass at a time, rebuild, reassess.
- **Parser brittleness: build output format shifts.** Swift/Bazel output is stable, but diagnostic-rendering flags could differ. Mitigation: after iteration 1, visually inspect a handful of error lines to confirm the `<file>:<line>:<col>: error:` pattern holds before automating iteration 2.
- **Stashing/snapshot failure** leaves the working tree in a half-dropped state. Mitigation: since every snapshot is branch HEAD, `git checkout -- <file>` always restores correctly. If the working tree is hopelessly messed up, `git checkout -- .` restores everything from HEAD — the whole wave can be safely restarted from scratch with zero loss.
- **Hidden `@_exported import Postbox` would bypass the sweep without being touched.** Intentional: those re-export Postbox and must stay. The `^import Postbox$` regex matches only plain imports.
- **Rule-2 compliance:** no new typealiases, no wrapper structs, no public API changes. ✅
## Abandonment criteria
- After 3 iterations, if new errors keep surfacing, the sweep's underlying assumption (per-file isolation) is broken for some module. Abandon: `git checkout -- .`, and record the blocker in CLAUDE.md's wave-6 outcome (not as a success). Consider manual per-file exploration in a future wave.
- If any iteration produces an error that isn't "cannot find type" / "use of unresolved identifier" / similar — halt, investigate, do not blindly restore.
## Expected outcome
- Dozens of `import Postbox` lines removed, all build-verified.
- Some consumer modules join the "Postbox-free" running tally when their last Postbox-importing file is swept.
- CLAUDE.md records the outcome and, for future waves, captures the methodology as permanent guidance so subsequent unused-import sweeps can be triggered any time imports accumulate.
- Zero behavior change.

89
docs/superpowers/specs/2026-04-20-decrypt-match-python-port-design.md
View file

@ -1,89 +0,0 @@
# Pure-Python port of `decrypt.rb` for fastlane match
## Goal
Drop the Ruby toolchain dependency from the iOS build. Replace the `ruby build-system/decrypt.rb` call in `BuildConfiguration.py:110` with a self-contained Python 3 implementation. No new third-party dependencies (no `cryptography` package, no Ruby).
## Current state
- `build-system/decrypt.rb` (115 lines) implements fastlane match's V1 (AES-256-CBC via `pkcs5_keyivgen` with MD5→SHA256 fallback) and V2 (AES-256-GCM with PBKDF2-derived key/iv/AAD + auth tag) decryption.
- `BuildConfiguration.py:103-118`'s `decrypt_codesigning_directory_recursively` shells out via `os.system('ruby build-system/decrypt.rb …')` per file.
- `build-system/Make/DecryptMatch.py` already exists as an aspirational Python port but is broken — its V2 implementation writes a literal placeholder string (`b"TEST_DECRYPTED_CONTENT"`) and the call site in `BuildConfiguration.py:115` is commented out.
- The production fastlane repo at `git@gitlab.com:peter-iakovlev/fastlanematch.git` stores files in V2 format (verified: base64 prefix decodes to `match_encrypted_v2__`). V2 must work.
## Constraints
- Stock macOS `python3` (3.9.6). Only Python stdlib may be used (`hashlib`, `hmac`, `base64`, `os`).
- Apple-shipped `openssl enc` CLI rules out the shell-out path for V2 because it does not accept AAD for GCM.
- The Ruby script's semantics are authoritative; the port must be byte-identical on the existing repo contents.
## Approach
Rewrite `build-system/Make/DecryptMatch.py` from scratch as a pure-Python AES implementation.
**AES-256 primitive.** Standard tables-based implementation:
- `_SBOX` / `_INV_SBOX` (256 bytes each), `_RCON` (10 bytes).
- `_key_expansion(key)` → 15 × 16-byte round keys (Nk=8, Nr=14, Nb=4 for AES-256).
- `_aes_encrypt_block(block, rks)` and `_aes_decrypt_block(block, rks)` operating on 16-byte state via SubBytes / ShiftRows / MixColumns (and their inverses) plus AddRoundKey.
- MixColumns via the standard `xtime`-based GF(2^8) multiply.
**V1 — AES-256-CBC with OpenSSL's `EVP_BytesToKey`.** Ruby's `pkcs5_keyivgen(password, salt, 1, hash)` is `EVP_BytesToKey` with `count=1`:
```
D_0 = empty
D_i = hash(D_{i-1} || password || salt) # no inner iteration when count=1
material = D_1 || D_2 || ... # until ≥ 48 bytes
key = material[0:32]; iv = material[32:48]
```
CBC decrypt: per 16-byte block, inverse-cipher then XOR with previous ciphertext block (seed = `iv`). Strip PKCS#7 padding at the end (validate `1 ≤ pad ≤ 16` and all pad bytes equal). Try `md5` first; on failure (non-PKCS#7 tail or downstream error), retry with `sha256`, mirroring the Ruby `rescue` fallback.
**V2 — AES-256-GCM with PBKDF2-derived key + IV + AAD.** Key schedule matches Ruby exactly:
```
material = hashlib.pbkdf2_hmac('sha256', password, salt, 10_000, dklen=32+12+24)
key = material[0:32]; iv = material[32:44]; aad = material[44:68]
```
GCM decrypt (IV is 96-bit, the common case):
- `H = AES_encrypt(key, 0^128)` (GHASH subkey)
- `J0 = iv || 0x00000001`
- Stream the ciphertext via CTR starting from `inc32(J0)`; counter is the low 32 bits of the block, rolled over mod 2^32.
- `GHASH(H, aad, ciphertext)` = fold AAD (zero-padded to 16), then ciphertext (zero-padded to 16), then `len(aad)_64 || len(ct)_64` bits, via GF(2^128) multiplication with reduction polynomial `0xe1…00`.
- `T = GHASH output XOR AES_encrypt(key, J0)`; raise if `T != auth_tag`.
GF(2^128) multiply is the standard right-shift-with-conditional-reduce loop (per-bit; fine for the kilobytes-at-most we're decrypting).
**File I/O.** The fastlane match file is ASCII base64 (confirmed on the live repo). Read as text, strip whitespace, base64-decode, dispatch on the 20-byte V2 magic prefix vs. the 8-byte `Salted__` V1 prefix. Replace the text-vs-binary heuristic in the current broken implementation — that heuristic was wrong and is unnecessary.
**Public API.** Keep `decrypt_match_data(source_path, destination_path, password)` signature so `BuildConfiguration.py` can swap the shell-out for a direct call with a one-line change.
## Changes
1. **Rewrite `build-system/Make/DecryptMatch.py`** end to end: AES primitives, `EVP_BytesToKey`, CBC decrypt, GCM decrypt, MatchDataEncryption dispatch, `decrypt_match_data` entry point. Drop the `subprocess`/`tempfile` and placeholder-V2 code paths entirely.
2. **Flip `BuildConfiguration.py:103-118`** — replace the `os.system('ruby build-system/decrypt.rb …')` call with `decrypt_match_data(source_path, destination_path, password)`. Remove the dead commented line.
3. **Delete `build-system/decrypt.rb`**.
## Verification
Run the user-supplied command:
```
python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/build/telegram/telegram-bazel-cache \
generateProject \
--configurationPath ~/build/telegram/telegram-internal-tools/PrivateData/build-configurations/enterprise-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent
```
Success criteria: `generateProject` completes, the `decrypted/profiles/development/*.mobileprovision` files are valid plists parseable by `openssl smime` (which `copy_profiles_from_directory` does immediately after, so any decryption corruption would surface there), and the generated Xcode project has correct signing settings.
Cross-check during development: decrypt one sample file with both the old Ruby script and the new Python and compare `sha256sum`s byte-for-byte before running the full command.
## Non-goals
- V1 with salt-less files (the fastlane "no salt" format variant): the Ruby script doesn't handle it either.
- GCM with non-96-bit IV: PBKDF2 derivation fixes IV length at 12 bytes, so this case cannot arise.
- Streaming decryption for huge files: match files are at most a few MB.
- AES-128 / AES-192: unused by fastlane match.

195
docs/superpowers/specs/2026-04-21-swifttl-layered-schema-generation-design.md
View file

@ -1,195 +0,0 @@
# SwiftTL — Optional Layered Schema Generation
**Date:** 2026-04-21
**Tool:** `build-system/SwiftTL`
**Inputs this unblocks:** `telegram-ios-shared/tools/secret_scheme.tl`, invoked by `telegram-ios-shared/tools/generate_and_copy_scheme.sh` with `--api-prefix=SecretApi`.
**Consumers this targets:** `submodules/TelegramCore/Sources/State/ManagedSecretChatOutgoingOperations.swift`, `submodules/TelegramCore/Sources/State/ProcessSecretChatIncomingDecryptedOperations.swift` — both reference `SecretApi{8,46,73,101,144}.<Type>.<ctor>`, symbols currently provided by hand-maintained `submodules/TelegramApi/Sources/SecretApiLayer{8,46,73,101,144}.swift` files.
## Problem
`SwiftTL` parses a flat `.tl` schema and emits one flat `Api` namespace. `secret_scheme.tl` is not flat — it's a multi-version schema separated by `===N===` layer markers (11 layers: 8, 17, 20, 23, 45, 46, 66, 73, 101, 143, 144), where the same constructor name can reappear in later layers with a new constructor ID and new fields (e.g. `decryptedMessage` exists at layers 8, 17, 45, 73, each with a different ID and argument list).
Running `SwiftTL secret_scheme.tl … --api-prefix=SecretApi` today fails: `DescriptionParser` doesn't recognize `===N===` markers, and `Resolver` throws on the first duplicate constructor name. The secret-chat `SecretApi{N}.<Type>.<ctor>` structs that downstream code already uses are hand-maintained and out-of-sync with what SwiftTL would naturally produce.
## Goal
Extend `SwiftTL` with optional layered-schema support so that `secret_scheme.tl` round-trips through the same CLI: one invocation produces one Swift file per declared layer. Flat schemas (`swift_scheme.tl`) continue to produce byte-identical output.
Non-goal: a complete rewrite of the legacy hand-written `SecretApiLayer*.swift` format. Output is "close enough" — same sum-type enums, same constructor IDs, same serialize/parse bodies — not byte-for-byte identical to the legacy files. Existing consumers compile unchanged because they reference the public symbols (`SecretApi8.DecryptedMessage.decryptedMessage(...)`), which the generator preserves.
## Architecture
Four files change in `build-system/SwiftTL/Sources/SwiftTL/`. No new files, no new CLI flags.
### `DescriptionParsing.swift`
The public `parse(data:)` return type changes from a tuple `(constructors, functions)` to a new enum:
```swift
enum ParsedSchema {
case flat(constructors: [ConstructorDescription], functions: [ConstructorDescription])
case layered(layers: [(layerNumber: Int, constructors: [ConstructorDescription])])
}
```
**Detection rule.** If any non-empty line matches the regex `^===\d+===\s*$`, the schema is layered. Every non-skipped constructor must sit under a marker; constructors appearing before the first marker are attached to the lowest-numbered layer. Otherwise the schema is flat (today's behavior, unchanged).
**Input validation** (only enforced in the layered branch):
- Layer numbers must be positive integers and appear in strictly ascending order in the source. Parser throws otherwise.
- `---functions---` is forbidden in layered mode. Parser throws if seen.
- Empty layers (marker followed immediately by the next marker or EOF) are allowed. They produce an output file whose cumulative snapshot is identical to the previous layer's.
The existing `skipPrefixes` / `skipContains` filter (for `true`, `vector`, `error`, `null`, `{X:Type}`) applies unchanged to both branches.
### `Resolution.swift`
A new static method on `Resolver`:
```swift
static func resolveLayeredTypes(
layers: [(layerNumber: Int, constructors: [DescriptionParser.ConstructorDescription])]
) throws -> [(layerNumber: Int, types: [SumType])]
```
Algorithm — walks layers in input order, maintaining a running map `constructorsByName: [QualifiedName: (typeName: QualifiedName, constructor: DescriptionParser.ConstructorDescription)]`. For each layer:
1. For each constructor in the layer: if the name already exists in the running map with a different target type, remove it from the old type's entry before inserting under the new target type.
2. Insert or overwrite the constructor in the running map.
3. At the end of the layer section, build `[SumType]` from the current running map by grouping constructors by their target type and resolving argument type references (same machinery `resolveTypes(constructors:)` already uses, factored into shared helpers).
The output preserves per-layer IDs: layer 8's `decryptedMessage` has ID `0x1f814f1f`, layer 17's has `0x204d3878`, layer 46's has `0x36b091de`, layer 73's has `0x91cc4674` — each landing in its own independent `[SumType]` snapshot.
The existing `resolveTypes(constructors:)` and `resolveFunctions(…)` stay unchanged for the flat path.
### `CodeGeneration.swift`
A new static method on `CodeGenerator`:
```swift
static func generateLayered(
apiPrefix: String,
layerNumber: Int,
types: [SumType]
) throws -> (filename: String, source: String)
```
Returns filename `"\(apiPrefix)Layer\(layerNumber).swift"` and a source string in the shape described below. Reuses the existing private helpers `typeReferenceRepresentation`, `generateFieldSerialization`, `generateFieldParsing`, and `SumType.hasDirectReference(to:typeMap:)` unchanged — the per-argument serialize/parse logic is byte-identical between flat and layered output.
The flat `CodeGenerator.generate(…)` entry point is untouched.
### `main.swift`
Branches on the parser's return value:
```swift
switch try DescriptionParser.parse(data: data) {
case let .flat(constructors, functions):
// existing flow, unchanged
case let .layered(layers):
let resolved = try Resolver.resolveLayeredTypes(layers: layers)
try FileManager.default.createDirectory(
at: URL(fileURLWithPath: outputDirectoryPath),
withIntermediateDirectories: true)
for (layerNumber, types) in resolved {
let (filename, source) = try CodeGenerator.generateLayered(
apiPrefix: apiPrefix, layerNumber: layerNumber, types: types)
let filePath = URL(fileURLWithPath: outputDirectoryPath)
.appendingPathComponent(filename).path
_ = try? FileManager.default.removeItem(atPath: filePath)
try source.write(toFile: filePath, atomically: true, encoding: .utf8)
}
}
```
## Layer semantics
For each emitted layer `N`, the effective constructor set is the ordered union of all constructors declared in layers `L ≤ N`, where a constructor with a given `QualifiedName` in a later layer **replaces** the earlier entry (new ID, new arguments, potentially new target sum type). The latest winner is the only one that appears in layer `N`'s output; earlier IDs are not included in layer `N`'s dispatch table.
Constructors declared only in layers `> N` do not appear in layer `N`.
Pre-marker constructors (e.g. `boolFalse`, `boolTrue` in `secret_scheme.tl`) are attached to the lowest-numbered layer. Rationale: (1) keeps the rule uniform ("every constructor belongs to exactly one declared layer"), (2) matches the natural reading of the schema file, (3) has no observable effect today since no downstream consumer references `Bool` from a secret-schema layer.
## Output format (per layer)
Matches the shape of the existing hand-written `SecretApiLayer{N}.swift` files. One file per layer, named `{apiPrefix}Layer{N}.swift`.
```
<leading blank line>
fileprivate let parsers: [Int32 : (BufferReader) -> Any?] = {
var dict: [Int32 : (BufferReader) -> Any?] = [:]
dict[-1471112230] = { return $0.readInt32() }
dict[570911930] = { return $0.readInt64() }
dict[571523412] = { return $0.readDouble() }
dict[-1255641564] = { return parseString($0) }
// dict[0x0929C32F] = { return parseInt256($0) } — emitted iff any constructor
// in this layer's cumulative snapshot has a field of type Int256.
dict[<sid>] = { return {apiPrefix}{N}.<TypeName>.parse_<ctorName>($0) }
// ... one entry per (latest) constructor in the cumulative snapshot
return dict
}()
public struct {apiPrefix}{N} {
public static func parse(_ buffer: Buffer) -> Any? { ... }
fileprivate static func parse(_ reader: BufferReader, signature: Int32) -> Any? { ... }
fileprivate static func parseVector<T>(_ reader: BufferReader, elementSignature: Int32, elementType: T.Type) -> [T]? { ... }
public static func serializeObject(_ object: Any, buffer: Buffer, boxed: Swift.Bool) { ... }
public enum <TypeName1> { /* cases, serialize, parse_* */ }
public enum <TypeName2> { ... }
// ...
}
```
**Deliberate differences from the flat-mode `Api0/1/….swift` output:**
- Single file instead of `Api0` header + `Api{1..N}` sharded impl files.
- `public struct` for the namespace instead of `public enum`.
- Nested `public enum <TypeName>` declarations instead of extensions.
- No `Cons_*` helper classes; enum cases use the inline-args shape — i.e. `case decryptedMessage(randomId: Int64, randomBytes: Buffer, message: String, media: …)`. Note the flat generator has a dormant inline-args branch guarded by `useStructPattern = false` that is never taken today; the layered generator renders this shape directly rather than sharing that branch.
- No `descriptionFields()` method, no `TypeConstructorDescription` conformance on the enums.
- `parse_*` methods are `fileprivate`, not `public static`.
- No `---functions---` section (rejected upstream).
The `indirect` keyword is still emitted when a type transitively references itself, via the existing `SumType.hasDirectReference(to:typeMap:)` helper.
## CLI
Unchanged. `swift run SwiftTL <schema> <outputDir> [--api-prefix=<prefix>]`. Layered behavior auto-triggers on `===N===` marker presence. With `--api-prefix=SecretApi` on `secret_scheme.tl`, SwiftTL emits 11 files: `SecretApiLayer{8,17,20,23,45,46,66,73,101,143,144}.swift`.
## Out-of-scope follow-ups
### `generate_and_copy_scheme.sh`
Lives in `telegram-ios-shared/tools/` (sibling repo). Currently invokes SwiftTL on both schemas but only copies `NewScheme/Api*.swift` into `submodules/TelegramApi/Sources/`. After this SwiftTL change lands, the script gains:
```sh
rm -f ../../telegram-ios/submodules/TelegramApi/Sources/SecretApiLayer*.swift
cp NewSecretScheme/SecretApiLayer*.swift ../../telegram-ios/submodules/TelegramApi/Sources/
```
The SwiftTL change produces the right files; the shell-script wiring is a follow-up commit in the sibling repo.
### `submodules/TelegramApi/BUILD`
If `submodules/TelegramApi/BUILD` lists the existing `SecretApiLayer{8,46,73,101,144}.swift` explicitly, it must be updated to include the 6 new layer files (17, 20, 23, 45, 66, 143) before the project will build. Implementation step: grep BUILD for `SecretApiLayer` at the start of implementation — if explicit, either add the 6 new file entries or switch to a `glob(["Sources/SecretApiLayer*.swift"])` pattern, in the same commit that introduces the files.
## Verification
No unit tests exist in this repo (per `CLAUDE.md`). Verification steps:
1. **Layered schema compiles.** `swift run SwiftTL <path>/secret_scheme.tl /tmp/out --api-prefix=SecretApi` succeeds and produces 11 files.
2. **Generated files match legacy by semantics.** Spot-check `SecretApiLayer8.swift`, `SecretApiLayer46.swift`, `SecretApiLayer73.swift`, `SecretApiLayer101.swift`, `SecretApiLayer144.swift` against their hand-written counterparts in `submodules/TelegramApi/Sources/`. Confirm:
- Same set of enum case names per sum type.
- Same constructor IDs in the dispatch table (latest per name only).
- Same argument ordering and types.
- Same indirect-ness for self-referential types.
Cosmetic differences (whitespace, per-helper indentation quirks, absence of `Cons_*`) are acceptable.
3. **Project builds.** Copy the generated files over the hand-written ones in `submodules/TelegramApi/Sources/`, run the full Bazel build (`source ~/.zshrc 2>/dev/null; Make.py build --continueOnError`), and confirm zero compilation errors. `ManagedSecretChatOutgoingOperations.swift` and `ProcessSecretChatIncomingDecryptedOperations.swift` reference `SecretApi{8,46,73,101,144}.<Type>.<ctor>` symbols that the generator preserves.
4. **Flat schema is unchanged.** `swift run SwiftTL <path>/swift_scheme.tl /tmp/out-main` succeeds; diff the generated `Api*.swift` against `submodules/TelegramApi/Sources/Api*.swift`. Expected: byte-identical (flat codepath untouched).
## Risks
- **Legacy-file semantic drift.** The hand-written `SecretApiLayer*.swift` files may contain micro-deviations from what the schema strictly implies (a constructor sneaked in by hand, an ID typo, an argument order tweak). Any such deviations will surface as compile or runtime-parse errors after regeneration. Mitigation: verification step 2 surfaces these before building; if found, the spec takes the schema as authoritative — legacy hand-edits get reverted, not preserved.
- **BUILD glob vs. explicit file list.** If BUILD lists files explicitly, adding the 6 new layer files (17, 20, 23, 45, 66, 143) requires a BUILD update in the same commit. Verification step during implementation.
- **Pre-marker constructor attribution.** `boolFalse`/`boolTrue` land in layer 8 under the spec. If the existing hand-written `SecretApiLayer8.swift` does not contain `Bool` (likely, since no consumer references it), the generator will add a nested `public enum Bool { case boolFalse; case boolTrue }` to layer-8 (and cumulatively to every subsequent layer) and two entries to each cumulative layer's dispatch dict. Harmless addition — build unaffected; diff noise only.

137
docs/superpowers/specs/2026-04-21-textstyleeditscreen-caret-tracking-design.md
View file

@ -1,137 +0,0 @@
# TextStyleEditScreen caret-tracking auto-scroll — design
## Background
`submodules/TelegramUI/Components/TextProcessingScreen/Sources/TextStyleEditScreen.swift` hosts a sheet built on `ResizableSheetComponent` with two `ListMultilineTextFieldItemComponent` fields (a title and a multi-line prompt). The sheet's `inputHeight` plumbing and scroll-content sizing have already been wired up:
- `TextStyleEditSheetComponent.View.update` passes `environmentValue.inputHeight` into `ResizableSheetComponentEnvironment(inputHeight:)` instead of a hardcoded `0.0`.
- `ResizableSheetComponent` now subtracts `inputHeight` from `topInset` and adds it to `scrollContentHeight` so the scroll view has enough room to pan past the keyboard.
What remains: when the user types, the caret in the focused field must be scrolled into the visible area above the soft keyboard. Without this, typing near the bottom of the prompt field hides the caret under the keyboard.
## Goal
Whenever a text edit occurs in either `ListMultilineTextFieldItemComponent` inside `TextStyleEditContentComponent`, adjust the enclosing scroll view's `bounds.origin.y` so that the caret rect sits comfortably above the keyboard and bottom action button.
## Scope
All changes live in `submodules/TelegramUI/Components/TextProcessingScreen/Sources/TextStyleEditScreen.swift`. No changes to `ResizableSheetComponent`, `ListMultilineTextFieldItemComponent`, or `TextFieldComponent` — their existing public surfaces are sufficient:
- `ListMultilineTextFieldItemComponent.Tag` (constructor param `tag:`, plus `matches(tag:)` on the view).
- `ListMultilineTextFieldItemComponent.View.textFieldView: TextFieldComponent.View?`.
- `TextFieldComponent.View.inputTextView: UITextView`.
- `TextFieldComponent.AnimationHint` attached as `userData` on the transition whenever `TextFieldComponent` fires a state update on text change (`TextFieldComponent.swift:471/491/504/542/620/1077`).
## Non-goals
- No scroll on focus change alone (user requirement — text-change only).
- No scroll on selection change without an edit.
- No scroll-triggering on keyboard show/hide independently of text changes.
- No changes to shared infrastructure (`ResizableSheetComponent` stays as-is after the user's sizing work).
## Design
### 1. Field tagging
`TextStyleEditContentComponent.View` stores two tags created once at init:
```swift
private let titleFieldTag = ListMultilineTextFieldItemComponent.Tag()
private let textFieldTag = ListMultilineTextFieldItemComponent.Tag()
```
The two `ListMultilineTextFieldItemComponent(...)` constructions in `update(...)` pass the corresponding tag via the existing `tag:` parameter (currently `tag: nil` at both sites). This lets us identify which of our fields a hint's originating `TextFieldComponent.View` belongs to.
### 2. Recenter trigger
At the end of `TextStyleEditContentComponent.View.update(...)`, after all sub-component layout is complete and all frames are set, evaluate the incoming transition's user data:
```swift
if let hint = transition.userData(TextFieldComponent.AnimationHint.self),
case .textChanged = hint.kind,
let hintView = hint.view {
self.recenterCaret(hintView: hintView, availableSize: availableSize, environment: environment, transition: transition)
}
```
`hint.kind` is either `.textChanged` or `.textFocusChanged(isFocused:)`; we match only `.textChanged`.
### 3. Scroll-to-caret logic
`recenterCaret(hintView:availableSize:environment:transition:)` is a private method on `TextStyleEditContentComponent.View` that performs these steps:
1. **Locate field view.** Walk ancestors of `hintView` up to the first `ListMultilineTextFieldItemComponent.View`. Confirm it matches one of `self.titleFieldTag` / `self.textFieldTag` via `fieldView.matches(tag:)`. If neither matches, bail silently.
2. **Compute caret rect in text-view space.** From the field view, grab `textFieldView?.inputTextView`. Retrieve the caret rect:
```swift
let endPosition = inputTextView.selectedTextRange?.end ?? inputTextView.endOfDocument
let caretRect = inputTextView.caretRect(for: endPosition)
```
If `caretRect.isNull` or `caretRect.isInfinite`, bail (text view hasn't laid out yet).
3. **Locate enclosing scroll view.** Walk `self.superview` chain until the first `UIScrollView` is found (this is `ResizableSheetComponent`'s private scroll view). If no scroll view is found, bail.
4. **Convert caret rect to scroll-view coordinates.**
```swift
let caretInScroll = inputTextView.convert(caretRect, to: scrollView)
```
5. **Compute visible region.** Within the scroll view's current bounds, determine the vertical range in which the caret should sit:
```swift
let bottomActionAreaHeight: CGFloat = 52.0 + 8.0 // matches ResizableSheetComponent bottom layout
let caretTopInset: CGFloat = 24.0 // small cushion below keyboard/button
let caretBottomInset: CGFloat = 24.0 // small cushion above keyboard/button
let visibleTop = scrollView.bounds.minY + caretTopInset
let visibleBottom = scrollView.bounds.maxY - environment.inputHeight - bottomActionAreaHeight - caretBottomInset
```
6. **Adjust `bounds.origin.y`.** Using the direct-assign + additive-animate pattern proven in `ComposePollScreen.swift:2873-2895`:
```swift
let previousBounds = scrollView.bounds
var newBounds = previousBounds
if caretInScroll.maxY > visibleBottom {
newBounds.origin.y += (caretInScroll.maxY - visibleBottom)
} else if caretInScroll.minY < visibleTop {
newBounds.origin.y -= (visibleTop - caretInScroll.minY)
}
let maxOriginY = max(0.0, scrollView.contentSize.height - scrollView.bounds.height)
newBounds.origin.y = min(max(0.0, newBounds.origin.y), maxOriginY)
if newBounds != previousBounds {
scrollView.bounds = newBounds
if !transition.animation.isImmediate {
let offsetY = previousBounds.origin.y - newBounds.origin.y
transition.animateBoundsOrigin(view: scrollView, from: CGPoint(x: 0.0, y: offsetY), to: CGPoint(), additive: true)
}
}
```
This keeps the scroll animation in sync with the text-change spring carried by the hint's transition, and matches existing precedent in the codebase.
## Edge cases
- **Caret rect unavailable.** `caretRect(for:)` returns `CGRect.null` or `CGRect.infinite` when the text view hasn't laid out. Skip — the next hint will cover it.
- **No enclosing scroll view.** Defensive bail; should never happen in normal operation but keeps the code robust against host refactors.
- **Hint from unrelated field.** Tag mismatch → bail. Keeps the scroll view untouched if a future nested text input is added.
- **Over/under-scroll.** `newBounds.origin.y` clamped to `[0, contentSize.height − bounds.height]`.
- **Caret already visible.** No-op — `newBounds != scrollView.bounds` guards against churn.
## File-level changes summary
Only `TextStyleEditScreen.swift` is edited:
- Add two stored `ListMultilineTextFieldItemComponent.Tag` properties on `TextStyleEditContentComponent.View`.
- Pass those tags into the existing two `ListMultilineTextFieldItemComponent(...)` calls in `update(...)`.
- Add a private `recenterCaret(...)` method on `TextStyleEditContentComponent.View`.
- Add a small block at the end of `update(...)` that reads `transition.userData(TextFieldComponent.AnimationHint.self)` and invokes `recenterCaret` when `.textChanged`.
Estimated diff size: ~40–60 lines added, no deletions.
## Verification
No unit tests exist in this project (per `CLAUDE.md`). Verification is a full `Make.py build` plus a manual smoke test:
1. Open `TextStyleEditScreen` in create mode on a simulator/device.
2. Tap the "Style Name" field. Confirm keyboard slides up and the "Create" button sits above the keyboard (pre-existing behavior from the user's `inputHeight` work).
3. Type a character — with short content no scroll should occur; the scroll view remains at origin zero.
4. Tap the "Instructions" field. Type enough text to push the field past the viewport. Confirm the caret stays ~24pt above the keyboard/button as each newline is added.
5. Scroll up manually to push the active field off-screen, then type one character — confirm the scroll view snaps back so the caret sits above the keyboard.
6. In edit mode on a long pre-populated prompt, tap in the middle of the prompt (no scroll expected per non-goals), then type one character — confirm the caret's line is pulled into view.

104
docs/superpowers/specs/2026-04-22-claude-md-reorganization-design.md
View file

@ -1,104 +0,0 @@
# CLAUDE.md reorganization — design
**Date:** 2026-04-22
**Status:** approved (brainstorm), pending plan
## Problem
`CLAUDE.md` has grown to 804 lines / ~99KB. It is loaded into every AI session in this repository, so its size directly consumes context budget that could be used for actual code work. It is also hard to navigate and maintain — the bulk is a per-wave changelog of the Postbox → TelegramEngine refactor, which obscures the rules, cheat sheets, and patterns that future waves actually need.
Two goals, weighted equally:
1. **Reduce always-loaded context size.** Target: CLAUDE.md shrinks to roughly ~200 lines / ~20KB (an ~80% reduction).
2. **Improve discoverability.** What remains in CLAUDE.md should be tight enough that an AI assistant can scan it and find the applicable rule or pattern without wading through narrative history.
## Current content breakdown
- Build / Code Style / Project Structure: ~35 lines — pure guidance, stays.
- Postbox refactor section: ~750 lines, further split:
- Standing rules 1–7: ~20 lines — active rules.
- Engine typealias cheat sheet: ~25 lines — active reference.
- MediaResource → EngineMediaResource patterns: ~30 lines — active patterns.
- Wave-selection guidance: ~150 lines — distilled lessons mixed with narrative backstory.
- Wave 1–26 outcomes: ~500 lines — history.
- Running tally of Postbox-free modules: ~30 lines — changelog-style enumeration.
- TelegramEngine.Resources facade inventory table: ~30 lines — active reference table.
- Known future-wave candidates: ~40 lines — planning state, duplicates memory file.
- Build command pointer: ~2 lines — duplicate of top-of-file section.
## Final structure
### CLAUDE.md (stays; slimmed)
Sections, in order:
1. **Build** — unchanged.
2. **Code Style Guidelines** — unchanged.
3. **Project Structure** — unchanged.
4. **Postbox → TelegramEngine refactor (in progress)**, containing:
- A brief intro paragraph plus a pointer: "Wave-by-wave history, full narrative lessons, running tallies, and example scripts live in `docs/superpowers/postbox-refactor-log.md` — read that file when you need wave-specific context or a full worked example."
- **Standing rules 1–7** — unchanged.
- **Engine typealias cheat sheet** — unchanged.
- **MediaResource → EngineMediaResource consumer migration** — unchanged.
- **Wave-selection guidance** — trimmed. Keep rules and recipes as terse bullets; drop narrative backstory, wave-specific iteration counts, full example scripts. Cross-reference the log file for backstory. Target: ~40–60 lines instead of ~150.
- **TelegramEngine.Resources facade inventory table** — unchanged (active reference table).
- The duplicate "Build command" pointer at the end is dropped (already covered at the top).
Everything that gets removed either moves to the log file or (for future-wave candidates) merges into the existing memory file.
### `docs/superpowers/postbox-refactor-log.md` (new file, not loaded by default)
- Short header explaining purpose: "Historical record of the Postbox → TelegramEngine refactor. Not loaded by default into AI sessions. AI assistants should read this file when they need wave-specific context, full worked examples of a pattern, or the running tally of module Postbox-freeness."
- Wave 1–26 outcomes verbatim (no edits).
- Running tally of Postbox-free modules.
- Full self-contained forms of each guidance subsection that gets trimmed in CLAUDE.md — the rule, the backstory, example scripts, iteration-count stories, and pre-migration inventories together, so a reader of the log file doesn't need to jump back to CLAUDE.md to know what rule the backstory supports. Each subsection has a stable anchor that the trimmed CLAUDE.md bullet can cross-reference.
### `project_postbox_refactor_next_wave.md` (existing memory file; updated)
- Merge in the four categories from CLAUDE.md's "Known future-wave candidates" section:
- Permanently blocked (4 classes conforming to `TelegramMediaResource`).
- Higher-friction mediaBox methods (cached representations, resourceData/resourceStatus sweeps, storageBox wrapping).
- Non-mediaBox established patterns (preferencesView sweep, `loadedPeerWithId` sweep).
- Standalone Postbox-class-move opportunities.
- Unused-import sweep re-run.
- Keep existing wave-27+ shortlist content.
## What "trim the guidance" concretely means
For each subsection under "Wave-selection guidance", the rule is **keep the actionable rule/recipe; drop the story**.
Worked example — current "Unused-import sweeps are a valid wave shape" is a ~35-line block with numbered methodology (steps 1–7), a script snippet, and an iteration-count anecdote ("18 → 4 → 5 → 3 → 12 → ..."). After trim in CLAUDE.md:
> **Unused-import sweeps** (wave-shape applied in waves 6, 14): speculatively drop `^import Postbox$`, build with `--continueOnError`, restore failures, iterate. After a few iterations, do pattern-based preemptive restores for files naming Postbox-only symbols. Scope never leaves the consumer-module candidate set — halt if errors surface in TelegramCore/Postbox/TelegramApi. Full methodology, scripts, and iteration stats in `postbox-refactor-log.md`.
Same treatment for the other guidance subsections:
- "Wave-selection guidance" (top-level "leaf module, drop Postbox in isolation" commentary)
- "Two feasible wave shapes" paragraph
- "Enum-payload migrations need a full case-site grep" paragraph
- "Public-Postbox-type inventory (wave-11-pattern planning)" paragraph — including the `postbox-public-types.txt` script
- "Wave-shape G: facade addition + consumer sweep in one commit" paragraph — keep the seven-step recipe, drop prose about wave-26 `RangeSet` example
## Implementation approach
Three commits, each self-contained:
1. **Create the log file.** Write `docs/superpowers/postbox-refactor-log.md` containing: header, Wave 1–26 outcomes verbatim, running tally of Postbox-free modules, verbose guidance passages extracted from CLAUDE.md. Commit.
2. **Rewrite CLAUDE.md.** Trim the guidance section to terse bullets with log-file cross-references, drop the wave outcomes and running tally sections, drop the duplicate build-command pointer at the bottom, add the log-file pointer near the start of the Postbox section. Commit.
3. **Update memory files.** Merge "Known future-wave candidates" into `project_postbox_refactor_next_wave.md`. Update `MEMORY.md` one-line index if its description of that file changes materially. Commit.
Commits are ordered so that if anyone reads HEAD at any point between commits, nothing is lost: commit 1 adds content without removing any, commit 2 removes content that's now in the log, commit 3 moves planning state to where it belongs.
## Non-goals
- No pruning or editing of the wave outcomes themselves. Verbatim move.
- No restructuring of the rest of `docs/` or of the `memory/` directory beyond the one-section merge.
- No changes to the build, code style, or project structure sections of CLAUDE.md.
## Success criteria
- CLAUDE.md ≤ ~250 lines / ~25KB. (Hard cap; stretch target ~200 lines / ~20KB.)
- Every guidance bullet in the trimmed CLAUDE.md either stands alone or has an explicit cross-reference to `postbox-refactor-log.md`.
- `postbox-refactor-log.md` contains Wave 1–26 outcomes verbatim — a diff between the removed-from-CLAUDE.md text and the added-to-log text should be empty.
- `project_postbox_refactor_next_wave.md` contains all five categories of future-wave candidates that previously lived in CLAUDE.md.
- No information is lost across the three commits.

227
docs/superpowers/specs/2026-04-24-contactlistpeer-engine-peer-migration-design.md
View file

@ -1,227 +0,0 @@
# Wave 36 — `ContactListPeer.peer` `Peer` → `EnginePeer`
Date: 2026-04-24
Status: approved design, awaiting plan
Wave shape: Peer-typed-API enum-case payload migration, single atomic commit (waves 34/35 pattern)
## Goal
Eliminate the Postbox-protocol `Peer` leak in the `ContactListPeer.peer(peer:isGlobal:participantCount:)` case payload by migrating the `peer` field from `Peer` to `EnginePeer`. Drop the outflow `._asPeer()` bridges that waves 33/34 installed at construction sites, and the inflow `EnginePeer(...)` wrappings at destructure sites. Apply wave 35's validated pre-flight pattern set (literal token + `.peer as?`/`is` + outflow-args + `EnginePeer(.peer)` + `._asPeer()`) to keep undercount below wave 35's 14%.
## Non-goals
- `ContactListPeerId.peer(PeerId)` (sibling enum, different payload) — unchanged; `PeerId == EnginePeer.Id` makes it already-clean.
- `canSendMessagesToPeer(_ peer: Peer, ignoreDefault: Bool) -> Bool` parameter migration — broader blast radius, deferred.
- `makePeerInfoController` / `makeChatQrCodeScreen` / `makeChatRecentActionsController` protocol-method migrations — broader blast radius, deferred.
- `openPeer(peer: Peer, ...)` / other Peer-typed APIs called from destructured bodies — if any destructured `peer` outflows into a raw-`Peer`-typed API after migration, add a `._asPeer()` bridge at that call site. Migrating those APIs is its own future wave.
- No new engine wrappers, typealiases, or facades introduced in this wave.
- No `import Postbox` drops in this wave — deferred to a follow-on unused-import sweep.
## Type change
```swift
// Before
public enum ContactListPeer: Equatable {
case peer(peer: Peer, isGlobal: Bool, participantCount: Int32?)
case deviceContact(DeviceContactStableId, DeviceContactBasicData)
public var id: ContactListPeerId { … }
public var indexName: PeerIndexNameRepresentation { … }
public static func ==(lhs: ContactListPeer, rhs: ContactListPeer) -> Bool {
switch lhs {
case let .peer(lhsPeer, lhsIsGlobal, lhsParticipantCount):
if case let .peer(rhsPeer, rhsIsGlobal, rhsParticipantCount) = rhs,
lhsPeer.isEqual(rhsPeer), // Postbox protocol method
lhsIsGlobal == rhsIsGlobal, lhsParticipantCount == rhsParticipantCount {
return true
} else { return false }
case let .deviceContact(id, contact):
if case .deviceContact(id, contact) = rhs { return true } else { return false }
}
}
}
// After
public enum ContactListPeer: Equatable {
case peer(peer: EnginePeer, isGlobal: Bool, participantCount: Int32?)
case deviceContact(DeviceContactStableId, DeviceContactBasicData)
public var id: ContactListPeerId { … } // body unchanged; peer.id is EnginePeer.Id == PeerId
public var indexName: EnginePeer.IndexName { … } // return type changed — body unchanged but type flows from EnginePeer.indexName
public static func ==(lhs: ContactListPeer, rhs: ContactListPeer) -> Bool {
switch lhs {
case let .peer(lhsPeer, lhsIsGlobal, lhsParticipantCount):
if case let .peer(rhsPeer, rhsIsGlobal, rhsParticipantCount) = rhs,
lhsPeer == rhsPeer, // EnginePeer is Equatable
lhsIsGlobal == rhsIsGlobal, lhsParticipantCount == rhsParticipantCount {
return true
} else { return false }
case let .deviceContact(id, contact):
if case .deviceContact(id, contact) = rhs { return true } else { return false }
}
}
}
```
The custom `==` is retained (rather than relying on synthesis) because `DeviceContactStableId` / `DeviceContactBasicData` conformance to Equatable is not verified here; minimising unrelated change. Only the `lhsPeer.isEqual(rhsPeer)` clause is rewritten.
## In-scope files
Scope based on the pre-flight Explore inventory plus a manual deep-scan pass that caught additional inflow wraps and Postbox-concrete casts the Explore agent missed. One definition file plus nine consumer files; seven of the consumer files need edits. Two (ComposeController, ChatSendAudioMessageContextPreview) have only `.id`-level accesses and should need no body change — plan verifies each during implementation.
### Category α — Definition (`AccountContext`)
**`submodules/AccountContext/Sources/ContactSelectionController.swift`**
- Line 62: enum case signature change `peer: Peer` → `peer: EnginePeer`.
- Line 74: computed property return type change `PeerIndexNameRepresentation` → `EnginePeer.IndexName`. Rationale: after the payload migration, `peer.indexName` at line 77 returns `EnginePeer.IndexName` (from `EnginePeer.indexName`), not `PeerIndexNameRepresentation`. Changing the return type up rather than re-bridging via `peer._asPeer().indexName` eliminates a Postbox-typed API from AccountContext and incidentally lets two `EnginePeer.IndexName(...)` wraps at ContactListNode:517 drop. The two enum case shapes match exactly — `EnginePeer.IndexName.title(title:addressNames:)` and `EnginePeer.IndexName.personName(first:last:addressNames:phoneNumber:)` are defined at `submodules/TelegramCore/Sources/TelegramEngine/Peers/Peer.swift:145-147` with the same parameter labels and types as `PeerIndexNameRepresentation`'s cases.
- Line 77: `return peer.indexName` — body unchanged; type now flows `EnginePeer → EnginePeer.IndexName`.
- Line 79: `return .personName(first: contact.firstName, last: contact.lastName, addressNames: [], phoneNumber: "")` — body unchanged; case resolution retargets to `EnginePeer.IndexName.personName`.
- Line 86: `==` operator — rewrite `lhsPeer.isEqual(rhsPeer)` to `lhsPeer == rhsPeer`.
- Line 67: `peer.id` same-type access (EnginePeer.id returns EnginePeer.Id ≡ PeerId) — unchanged.
### Category β — Outflow-bridge drops (the dominant pattern)
Every site below is `.peer(peer: <expr>._asPeer(), isGlobal: …, participantCount: …)` → `.peer(peer: <expr>, …)`, because `<expr>` is already `EnginePeer` at the call site.
**`submodules/ContactListUI/Sources/ContactListNode.swift`** — 12 sites: 632, 690, 701, 747, 765, 1365, 1647, 1656, 1693, 1731, 1942, 1944.
**`submodules/ContactListUI/Sources/ContactsSearchContainerNode.swift`** — 3 sites: 494, 535, 569.
**`submodules/TelegramUI/Sources/ContactMultiselectionController.swift`** — 2 bridged sites: 451, 459.
**`submodules/TelegramUI/Sources/ContactMultiselectionControllerNode.swift`** — 1 site: 317.
**`submodules/TelegramUI/Sources/ContactSelectionControllerNode.swift`** — 2 sites: 160, 230.
Total: 20 outflow-bridge drops.
### Category γ — Removed
Earlier draft flagged `TelegramUI/ContactMultiselectionController.swift:379` as a raw-`Peer` construction needing `EnginePeer(peer)` promotion. Rechecked: line 379 is inside a destructure at line 347 (`case let .peer(peer, _, _) = peer`), so post-migration the inner `peer` is already `EnginePeer` and the existing `.peer(peer: peer, ...)` continues to compile without wrapping. No edit needed.
### Category δ — Inflow-wrapping drops at destructure sites
Every site is `EnginePeer(peer)` applied to a destructured peer that becomes `EnginePeer` directly post-migration → drop each wrap.
- **ContactListNode.swift**: 4 wraps total.
- Line 204 wraps `peer` twice inside `.peer(peer: EnginePeer(peer), chatPeer: EnginePeer(peer))` (inside destructure at line 177).
- Line 252 wraps once inside `interaction.openDisabledPeer(EnginePeer(peer), …)` (inside destructure at line 251).
- Line 844 wraps once inside `isPeerEnabled(EnginePeer(peer))` (inside destructure at line 833).
- **ContactsController.swift**: 1 wrap — line 294 `chatLocation: .peer(EnginePeer(peer))` where `peer` is destructured at line 287.
- **ContactsSearchContainerNode.swift**: 4 wraps total.
- Line 164 `peerItem = .peer(peer: EnginePeer(peer), chatPeer: EnginePeer(peer))` (2 wraps, inside destructure at line 163).
- Line 165 `nativePeer = EnginePeer(peer)` (1 wrap, same destructure).
- Line 181 `openDisabledPeer(EnginePeer(peer), …)` (1 wrap, inside destructure at line 180).
- **TelegramUI/Sources/ContactMultiselectionController.swift**: 4 wraps total.
- Line 386 `subject: .peer(EnginePeer(peer))` (inside destructure at line 347).
- Line 403 `subject: .peer(EnginePeer(peer))` (same destructure).
- Line 481 `self.params.sendMessage?(EnginePeer(peer))` (inside destructure at line 468).
- Line 491 `self.params.openProfile?(EnginePeer(peer))` (same destructure).
- **TelegramUI/Sources/ContactMultiselectionControllerNode.swift**: 1 wrap — line 492 `EnginePeer(peer).compactDisplayTitle` (inside destructure at line 491).
- **TelegramUI/Sources/ContactSelectionController.swift**: 2 wraps total.
- Line 517 `self.sendMessage?(EnginePeer(peer))` (inside destructure at line 504).
- Line 527 `self.openProfile?(EnginePeer(peer))` (same destructure).
Total: 16 inflow-wrap drops.
### Category φ — Postbox-concrete cast rewrites
Destructured `peer` post-migration is `EnginePeer`. Existing `peer as? TelegramUser`/`TelegramGroup`/`TelegramChannel` casts no longer compile; rewrite to `EnginePeer` case-pattern matches. Both sites are in `ContactListNode.swift`.
- **ContactListNode.swift:182-186** — inside destructure at line 177. Rewrite the `if let _ = peer as? TelegramUser { … } else if let group = peer as? TelegramGroup { … } else if let channel = peer as? TelegramChannel { … }` chain to `switch peer { case .user: … case let .legacyGroup(group): … case let .channel(channel): … default: break }`, or equivalently to the `if case .user = peer / if case let .legacyGroup(group) = peer / if case let .channel(channel) = peer` chain. Inner `group.participantCount`, `channel.info`, `case .group = channel.info` continue to compile unchanged because `EnginePeer.channel` / `.legacyGroup` wrap the exact same concrete types (`TelegramChannel`, `TelegramGroup`) and `.user` wraps `TelegramUser`. Note: the original `if let _ = peer as? TelegramUser` branch doesn't bind the user — rewrite keeps that (either `case .user = peer` or `if case .user = peer`).
- **ContactListNode.swift:1968** — inside destructure at line 1966. Rewrite `let user = peer as? TelegramUser` to `case let .user(user) = peer`. Inner `user.phone` continues to compile (`EnginePeer.user` wraps `TelegramUser`).
EnginePeer enum case mapping (reference):
| Postbox concrete | EnginePeer case |
|---|---|
| `TelegramUser` | `.user(TelegramUser)` |
| `TelegramGroup` | `.legacyGroup(TelegramGroup)` |
| `TelegramChannel` | `.channel(TelegramChannel)` |
Lines 1802, 1818, 1820 in ContactListNode.swift also contain `peer as? TelegramChannel`/`peer is TelegramGroup` casts but these are on `peer` values sourced from `entryData.renderedPeer.peer` (raw Postbox `Peer`), not from a ContactListPeer destructure. They stay unchanged — out of wave scope.
### Category ε′ — `ContactListPeer.indexName` return-type cascade
Because category α changes the return type of `ContactListPeer.indexName` to `EnginePeer.IndexName`, call sites that currently wrap that return in `EnginePeer.IndexName(...)` can drop the wrap:
- **ContactListNode.swift:517** — `let result = EnginePeer.IndexName(lhs.indexName).isLessThan(other: EnginePeer.IndexName(rhs.indexName), ordering: sortOrder)` → `let result = lhs.indexName.isLessThan(other: rhs.indexName, ordering: sortOrder)`. Two wraps drop. The `isLessThan(other:ordering:)` extension is defined on `EnginePeer.IndexName` only (see `submodules/LocalizedPeerData/Sources/PeerTitle.swift:64`), so the existing wrap idiom was required pre-migration.
- **ContactListNode.swift:539, 590** — `switch peer.indexName` / `switch orderedPeers[i].indexName` with `case let .title(…)` and `case let .personName(…)` — continues to compile unchanged. Same case names and shapes.
### Category ε — Same-type field access (no edit)
Destructured peer bindings whose only uses are `.id`, `.addressName`, value equality via `.id`, etc. All of these exist on `EnginePeer` with identical semantics.
Known sites from inventory (accept as same-type):
- **ContactSelectionController.swift**: 67, 76 — `.id`, `.indexName`.
- **ContactListNode.swift**: 121, 177, 209, 216, 251, 255, 491, 505, 519, 520, 782, 787, 827, 833, 1636, 1966 — `.id`/`.addressName`/value comparisons on `.id`. Sites 204 and 251 also appear in category δ because the same binding is used both ways in the same block.
- **ContactsSearchContainerNode.swift**: 151 — `.addressName`.
- **ContactMultiselectionController.swift**: 347, 468 — `.id`.
- **ContactMultiselectionControllerNode.swift**: 491 — `selectedPeers.first` destructure to access `.id`.
- **ContactSelectionController.swift (TelegramUI)**: 504 — context-action passthrough.
- **ComposeController.swift**: 120, 160 — `.id` for chat creation.
- **ChatSendAudioMessageContextPreview.swift**: 88 — `.contact`/name accessors.
These need no code edits; they are listed only to record coverage.
### Category ζ — Outflow-to-`Peer`-typed-API (bridge required)
Any destructured `peer` (now `EnginePeer`) passed to a function that takes raw `Peer` needs `._asPeer()` appended at the call site.
Known candidate from inventory:
- **ContactsSearchContainerNode.swift:180** — `isPeerEnabled(peer)`. Verify the parameter type at edit time. If it is `(EnginePeer) -> Bool`, no bridge needed; if `(ContactListPeer) -> Bool`, also no bridge (the destructured value is discarded for the overall `peer` value anyway). If `(Peer) -> Bool`, add `._asPeer()`.
Plan-time step 7 verifies each category-ε site against the API it feeds into; any surprise is resolved by adding `._asPeer()` inline.
## Out-of-scope — name collisions
Files listed in the 20-file grep but not touched in this wave:
- **PeerInfoUI/ChannelMembersController.swift**, **PeerInfoUI/ChannelVisibilityController.swift**, **SettingsUI/…/GlobalAutoremoveScreen.swift**, **IncomingMessagePrivacyScreen.swift**, **SelectivePrivacySettingsController.swift**, **SelectivePrivacySettingsPeersController.swift**, **PresentAddMembers.swift**, **ComposeController.swift (TelegramUI)**, **OpenResolvedUrl.swift**, **ChatSendAudioMessageContextPreview.swift** — the inventory found only `ContactListPeerId.peer(…)` destructures or pass-throughs of the entire `ContactListPeer` enum value, not `ContactListPeer.peer` payload access. The payload-type migration does not affect these.
Plan-time verification: re-grep these files for `case .peer(let peer`, `case let .peer(peer,`, and `.peer(peer:` before declaring "no edits needed". If a missed payload destructure surfaces, promote the file into scope.
## Execution plan outline (for writing-plans)
Single atomic commit ordering:
1. Edit `AccountContext/ContactSelectionController.swift` — change case payload type (L62); change `indexName` property return type to `EnginePeer.IndexName` (L74); rewrite `lhsPeer.isEqual(rhsPeer)` to `lhsPeer == rhsPeer` (L86).
2. Edit `ContactListNode.swift` — drop 12 `._asPeer()` bridges (outflow); drop 4 inflow `EnginePeer(peer)` wraps (2 on L204, 1 on L252, 1 on L844); rewrite cast chain at L182-186 to EnginePeer case patterns; rewrite cast at L1968; drop 2 `EnginePeer.IndexName(...)` wraps on L517.
3. Edit `ContactsController.swift` — drop 1 inflow `EnginePeer(peer)` wrap at L294.
4. Edit `ContactsSearchContainerNode.swift` — drop 3 `._asPeer()` bridges at L494/535/569; drop 4 inflow `EnginePeer(peer)` wraps (2 on L164, 1 on L165, 1 on L181). Do NOT drop `._asPeer()` at L488/528/562 (these feed `canSendMessagesToPeer(_: Peer)` — deferred wave).
5. Edit `TelegramUI/ContactMultiselectionController.swift` — drop 2 outflow bridges at L451/459; drop 4 inflow wraps at L386/403/481/491. Do NOT edit L171/201/748 (these feed `peerTokenTitle(peer: Peer)` — deferred).
6. Edit `TelegramUI/ContactMultiselectionControllerNode.swift` — drop 1 outflow bridge at L317; drop 1 inflow wrap at L492.
7. Edit `TelegramUI/ContactSelectionController.swift` — drop 2 inflow wraps at L517/527.
8. Edit `TelegramUI/ContactSelectionControllerNode.swift` — drop 2 outflow bridges at L160/230.
9. Verify `ComposeController.swift` and `ChatSendAudioMessageContextPreview.swift` need no body edits. If build surfaces a leak, fold the fix into an additional task step.
10. Build: `source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 --configuration=debug_sim_arm64 --continueOnError`.
11. Address undercount misses (expected ≤3 — pre-flight was thorough but file count is large) and commit once build is green.
## Risk register
| Risk | Mitigation |
|------|------------|
| Inventory undercount (wave 35 had 14%; trend decreasing) | Pre-flight already uses validated pattern set. `--continueOnError` on the build surfaces all misses in one pass. Expected ≤2 missed sites. |
| Destructure sites that flow a peer into a raw-`Peer`-typed API (category ζ) not caught by inventory | Build will flag the type mismatch; fix inline with `._asPeer()` at the flagged call site. Plan step 8 is the explicit verification gate. |
| `ContactListPeer` Equatable semantic regression | Replacing `lhsPeer.isEqual(rhsPeer)` (Postbox dynamic dispatch) with `lhsPeer == rhsPeer` (EnginePeer synthesized `==`) compares the same underlying concrete types (`.user(TelegramUser)`, `.channel(TelegramChannel)`, etc.) via their own Equatable conformances. Truth table preserved. |
| `ContactListPeer.indexName` return-type change cascades beyond ContactListNode:517/539/590 | Consumers of `ContactListPeer.indexName` enumerated via `grep -rn "\.indexName" submodules/ --include="*.swift"` filtered for ContactListPeer-typed receivers: only ContactListNode has such uses. No other submodule destructures or pattern-matches on this property. Build will flag any miss immediately. |
| `peer.isEqual` used elsewhere in scope files but on non-ContactListPeer bindings | Inventory confirmed ContactListNode:306 uses `!=` on a `ContactListNodeEntry.peer` binding, not `ContactListPeer.peer`. Scope boundary respected. No other `isEqual` call on a ContactListPeer-destructured binding was found. |
| Files flagged "no ContactListPeer.peer payload access" turn out to have one | Plan step 8 re-greps these files; any hit gets promoted into scope without rerunning the wave. |
| Pre-existing WIP on `ChatListFilterPresetController.swift` / `ChatListFilterPresetListController.swift` | Out of wave scope — untouched. No ContactListPeer reference expected in those files. |
## Validation
- Full Bazel build (`--configuration=debug_sim_arm64 --continueOnError`).
- No TelegramCore/Postbox/TelegramApi errors (scope boundary check — halt if they surface).
- Grep post-commit: `rg "ContactListPeer\.peer\(peer: .*\._asPeer" submodules/` returns empty.
- Grep post-commit: `rg "case \.peer\(peer: .*\._asPeer" submodules/` returns empty (catch shortcut constructions).
- Grep post-commit: no surviving `EnginePeer\(peer\)` in the 10 touched files where `peer` was destructured from a `ContactListPeer.peer` case (manual spot-check — automated grep too noisy).
## Lessons to carry forward
- Wave 35's pre-flight pattern set (literal token + `.peer as?`/`is` + outflow-args + `EnginePeer(.peer)` + `._asPeer()`) applied to this wave; record the post-commit undercount percentage to continue the calibration trend (wave 34: ~33%, wave 35: ~14%).
- This wave is dominated by **bridge removal** — 20 outflow `._asPeer()` drops + 16 inflow `EnginePeer(peer)` drops + 2 `EnginePeer.IndexName(...)` drops + 1 `.isEqual` → `==` fix + 2 Postbox-cast chain rewrites. Zero bridge additions. Updated tallies supersede earlier draft counts in this spec. Confirms the ratchet effect: earlier waves added bridges at Peer/EnginePeer boundaries precisely so future waves like this one can drop them atomically. Record the ratio (bridge drops : bridge additions) as a health metric across Peer-typed-API waves.
- Custom enum `==` operators using `Peer.isEqual(_:)` are a predictable Category-F leak in every Peer-payload migration. Future Peer-typed-API waves should grep the enum's defining module for `\.isEqual\(` specifically.
- **Computed properties on the enum that return Postbox types (e.g., `PeerIndexNameRepresentation`) are a second predictable leak** — discovered mid-spec for `ContactListPeer.indexName`. Future Peer-typed-enum waves should grep the enum's definition file for `public var` / `public func` returning any Postbox-defined type (`PeerIndexNameRepresentation`, `PeerNameIndex`, `MessageId`, etc.) before committing to the inventory — changing the return type to the Engine equivalent frequently cascades into consumer-side wrap drops (here, 2 wraps at ContactListNode:517).

193
docs/superpowers/specs/2026-04-24-foundpeer-engine-peer-migration-design.md
View file

@ -1,193 +0,0 @@
# Wave 34 Design: `FoundPeer.peer: Peer → EnginePeer`
**Date:** 2026-04-24
**Wave:** 34 (Postbox → TelegramEngine refactor)
**Predecessor:** Wave 33 (loadedPeerWithId consumer sweep, commit `16d017853a`)
## Goal
Migrate the public field `FoundPeer.peer` from the Postbox `Peer` protocol to the TelegramCore `EnginePeer` enum. Drops 4 of the 5 `._asPeer()` bridges introduced by wave 33 and eliminates one Postbox-protocol leak from a `TelegramEngine.Contacts` / `TelegramEngine.Calls` return type.
## Non-Goals
- Migrating other Peer-typed-API surfaces (`SendAsPeer`, `makePeerInfoController`, `makeChatRecentActionsController`, `makeChatQrCodeScreen`, `FoundPeer` is the smallest probe in this class — those are separate future waves).
- Dropping `import Postbox` from `SearchPeers.swift`. The `_internal_*` functions in that file still call `postbox.transaction`, `parseTelegramGroupOrChannel`, `AccumulatedPeers`, `updatePeers`. They remain the Postbox-facing layer per project rule.
- Dropping `import Postbox` from any consumer module. None of the touched files reach zero Postbox use through this change alone.
- Auto-synthesizing `Equatable` for `FoundPeer`. Manual `==` is preserved per user decision.
## Scope
One atomic commit. Approximately 46 semantic edits plus type-name continuations across:
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/SearchPeers.swift` (definition + `_internal_searchPeers` body)
- 7 consumer files in `submodules/`:
- `submodules/TelegramCallsUI/Sources/VideoChatScreen.swift`
- `submodules/TelegramCallsUI/Sources/VideoChatScreenMoreMenu.swift`
- `submodules/ContactListUI/Sources/ContactListNode.swift`
- `submodules/ChatListUI/Sources/ChatListSearchListPaneNode.swift`
- `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreenCallActions.swift`
- `submodules/TelegramBaseController/Sources/TelegramBaseController.swift`
- `submodules/SettingsUI/Sources/Data and Storage/StorageUsageExceptionsScreen.swift`
The remaining ~10 files identified by `grep -rln "FoundPeer\b"` (StorageUsageExceptionsScreen field-only refs aside, the file IS in the touched list above) contain only C5 type-name mentions or unrelated `.peer.peer` accesses on other types and require no edit.
**Verification (performed 2026-04-24)** that nearby `EnginePeer(peer.peer)` patterns in other files are NOT FoundPeer access: those sites bind `peer` to `SelectivePrivacyPeer`, `SendAsPeer`, `InactiveChannel`, `RenderedChannelParticipant`, or `RenderedPeer` — all of which still expose `.peer: Peer`. They remain unchanged by this wave.
## Changes
### 1. `submodules/TelegramCore/Sources/TelegramEngine/Peers/SearchPeers.swift`
**Struct:**
```swift
public struct FoundPeer: Equatable {
public let peer: EnginePeer // was: Peer
public let subscribers: Int32?
public init(peer: EnginePeer, subscribers: Int32?) { // was: peer: Peer
self.peer = peer
self.subscribers = subscribers
}
public static func ==(lhs: FoundPeer, rhs: FoundPeer) -> Bool {
return lhs.peer == rhs.peer && lhs.subscribers == rhs.subscribers
// was: lhs.peer.isEqual(rhs.peer) && lhs.subscribers == rhs.subscribers
}
}
```
**`_internal_searchPeers` body changes:**
- All four `FoundPeer(peer: peer, subscribers: …)` constructions (lines 70, 72, 85, 87) wrap the raw `peer` value with `EnginePeer(peer)`.
- Six scope-filter expressions (2 per non-trivial scope × 3 scopes — `.channels` lines 96–109, `.groups` lines 110–128, `.privateChats` lines 129–143) rewrite to enum pattern matching:
- `as? TelegramChannel, case .broadcast = channel.info` → `if case let .channel(channel) = item.peer, case .broadcast = channel.info`
- `as? TelegramChannel, case .group = channel.info` plus `else if item.peer is TelegramGroup` → `if case let .channel(channel) = item.peer, case .group = channel.info` plus `else if case .legacyGroup = item.peer`
- `if item.peer is TelegramUser` → `if case .user = item.peer`
Filter behavior is preserved exactly; only the destructuring form changes.
### 2. Consumer-side edits (by category)
Inventory was performed on 2026-04-24 via Explore agent against the 10 files identified by `grep -rln "FoundPeer\b" submodules/ Telegram/`. An additional 3 files surfaced (`ShareControllerNode.swift`, `SharePeersContainerNode.swift`, `PeerSelectionControllerNode.swift`, `ContactSelectionControllerNode.swift`, `ChatListNode.swift`) — most are C5 type-name mentions or false positives in field names that don't reference the type.
**C1 — peer-protocol method reads (~28 sites): no edit required.**
`peer.peer.id`, `peer.peer.displayTitle`, `peer.peer.namespace`, `peer.peer.debugDisplayTitle`, `peer.peer.smallProfileImage` — all available on `EnginePeer` with the same signatures.
**C5 — type-signature mentions (~60 sites): no edit required.**
`[FoundPeer]`, `Signal<([FoundPeer], [FoundPeer]), NoError>`, `Atomic<([FoundPeer], [FoundPeer])?>`, `case globalPeer(FoundPeer, …)`, etc. The type continues to compile under the new field.
**C2 — downcast rewrites (30 sites).**
EnginePeer is an enum, so `peer.peer as? TelegramX` / `peer.peer is TelegramX` patterns must rewrite to `if case .X = peer.peer` (or `if case let .X(x) = peer.peer` when the bound value is reused). Case mapping:
- `TelegramUser` → `.user`
- `TelegramSecretChat` → `.secretChat`
- `TelegramGroup` → `.legacyGroup`
- `TelegramChannel` → `.channel`
| File | Line | Current pattern | After (representative) |
|---|---|---|---|
| `TelegramCallsUI/VideoChatScreenMoreMenu.swift` | 628 | `peer.peer is TelegramGroup` | `if case .legacyGroup = peer.peer` |
| `TelegramCallsUI/VideoChatScreenMoreMenu.swift` | 631 | `as? TelegramChannel, case .group = peer.info` | `if case let .channel(channel) = peer.peer, case .group = channel.info` |
| `TelegramCallsUI/VideoChatScreenMoreMenu.swift` | 648 | `as? TelegramChannel, case .broadcast = peer.info` | `if case let .channel(channel) = peer.peer, case .broadcast = channel.info` |
| `ContactListUI/ContactListNode.swift` | 1501 | `if let _ = peer.peer as? TelegramChannel` | `if case .channel = peer.peer` |
| `ContactListUI/ContactListNode.swift` | 1563, 1569, 1574 | `if let user = peer.peer as? TelegramUser, user.flags.contains(.requirePremium)` | `if case let .user(user) = peer.peer, user.flags.contains(.requirePremium)` |
| `ContactListUI/ContactListNode.swift` | 1658, 1665, 1695, 1703, 1733 | `let user = peer.peer as? TelegramUser` (in if-let chains) | `if case let .user(user) = peer.peer, …` |
| `ContactListUI/ContactListNode.swift` | 1673, 1711 | `if peer.peer is TelegramGroup` (with possible `&& <bool>`) | `if case .legacyGroup = peer.peer` (with `, <bool>`) |
| `ContactListUI/ContactListNode.swift` | 1675, 1713 | `else if let channel = peer.peer as? TelegramChannel` | `else if case let .channel(channel) = peer.peer` |
| `ChatListUI/ChatListSearchListPaneNode.swift` | 1024 | `!(peer.peer is TelegramUser \|\| peer.peer is TelegramSecretChat)` | rewrite to combined enum-pattern (×2 within the line) |
| `ChatListUI/ChatListSearchListPaneNode.swift` | 1029, 1030 | `if let _ = peer.peer as? TelegramGroup` / `else if let peer = peer.peer as? TelegramChannel, case .group = peer.info` | `if case .legacyGroup = peer.peer` / `else if case let .channel(channel) = peer.peer, case .group = channel.info` |
| `ChatListUI/ChatListSearchListPaneNode.swift` | 1038, 1040 | `if peer.peer is TelegramUser` / `else if let channel = peer.peer as? TelegramChannel, case .broadcast = channel.info` | `if case .user = peer.peer` / `else if case let .channel(channel) = peer.peer, case .broadcast = channel.info` |
| `ChatListUI/ChatListSearchListPaneNode.swift` | 1500, 1507 | `if let channel = peer.peer as? TelegramChannel, case .broadcast = channel.info` | `if case let .channel(channel) = peer.peer, case .broadcast = channel.info` |
| `PeerInfoScreen/PeerInfoScreenCallActions.swift` | 175, 178, 193 | (see prior lines, same pattern set) | (same) |
| `TelegramBaseController/TelegramBaseController.swift` | 243, 246, 258 | `peer.peer is TelegramGroup` / `as? TelegramChannel, case .group = peer.info` / `as? TelegramChannel, case .broadcast = peer.info` | (same enum-pattern rewrites as above) |
Two name-shadowing notes:
- **Inner `peer` shadowing.** Several rewrites (e.g., `else if let peer = peer.peer as? TelegramChannel`) currently shadow the loop variable with a new `peer` of type `TelegramChannel`. After rewrite these become `else if case let .channel(channel) = peer.peer` — the binding name moves from `peer` to `channel` to avoid further shadowing of the EnginePeer loop variable. Adjust subsequent body references inside the if-let scope (they currently say `peer.info` referring to `TelegramChannel.info`; they become `channel.info`). Spot-check each rewrite within its block.
- **`channel.info` references.** When a downcast block uses the bound `peer` for `.info` access (e.g., line 178: `peer.info`), update those references to use the new binding name (`channel.info`). Block-internal-only — no cascade.
Plus 6 filter sites inside `SearchPeers.swift` `_internal_searchPeers` body (already counted under §1).
**C4 — constructor edits (6 sites):**
Bridge-drop sites — wave-33 added `._asPeer()` because the value was already `EnginePeer`; with this wave the field accepts EnginePeer directly:
| File | Line | Current | After |
|---|---|---|---|
| `TelegramCallsUI/VideoChatScreen.swift` | 1833 | `FoundPeer(peer: peer._asPeer(), subscribers: nil)` | `FoundPeer(peer: peer, subscribers: nil)` |
| `ContactListUI/ContactListNode.swift` | 1485 | `FoundPeer(peer: mainPeer._asPeer(), subscribers: nil)` | `FoundPeer(peer: mainPeer, subscribers: nil)` |
| `ContactListUI/ContactListNode.swift` | 1517 | `FoundPeer(peer: $0._asPeer(), subscribers: nil)` (inside `peers.map { … }`) | `FoundPeer(peer: $0, subscribers: nil)` |
| `TelegramBaseController/TelegramBaseController.swift` | 208 | `FoundPeer(peer: peer._asPeer(), subscribers: nil)` | `FoundPeer(peer: peer, subscribers: nil)` |
| `PeerInfoScreen/PeerInfoScreenCallActions.swift` | 156 | `FoundPeer(peer: peer._asPeer(), subscribers: nil)` | `FoundPeer(peer: peer, subscribers: nil)` |
| `PeerInfoScreen/PeerInfoScreenCallActions.swift` | 265 | `FoundPeer(peer: peer._asPeer(), subscribers: nil)` | `FoundPeer(peer: peer, subscribers: nil)` |
Wrap-needed sites — value at the call site is raw `Peer`, must be wrapped:
| File | Line | Current | After |
|---|---|---|---|
| `ContactListUI/ContactListNode.swift` | 1506 | `mappedPeers.append(FoundPeer(peer: peer.peer, subscribers: subscribers))` | already-EnginePeer (since `peer: FoundPeer` after migration) → `mappedPeers.append(FoundPeer(peer: peer.peer, subscribers: subscribers))` — **no edit** |
| `SettingsUI/StorageUsageExceptionsScreen.swift` | 288 | `FoundPeer(peer: peer, subscribers: subscriberCount)` | `FoundPeer(peer: EnginePeer(peer), subscribers: subscriberCount)` |
Note: ContactListNode:1506 is inside a `for peer in mappedPeers` over `[FoundPeer]`, so `peer.peer` is already `EnginePeer` after migration. No edit. Re-classified from C4-wrap-needed to no-op.
So: 4 bridge-drop edits + 1 actual wrap (StorageUsageExceptionsScreen:288) = 5 C4 edits, not 6.
**C3 — drop redundant `EnginePeer(peer.peer)` wrap (22 sites).**
After migration `peer.peer` is already `EnginePeer`, and `EnginePeer.init(_ peer: Peer)` does not accept an EnginePeer argument — so each `EnginePeer(peer.peer)` wrap MUST be dropped to just `peer.peer` or the build fails.
| File | Line | Wraps | Pattern (representative) |
|---|---|---|---|
| `SettingsUI/StorageUsageExceptionsScreen.swift` | 173 | 1 | `EnginePeer(peer.peer).displayTitle(…)` → `peer.peer.displayTitle(…)` |
| `SettingsUI/StorageUsageExceptionsScreen.swift` | 176 | 1 | `iconPeer: EnginePeer(peer.peer)` → `iconPeer: peer.peer` |
| `TelegramBaseController/TelegramBaseController.swift` | 265 | 2 | `peer: EnginePeer(peer.peer), title: EnginePeer(peer.peer).displayTitle(…)` → `peer: peer.peer, title: peer.peer.displayTitle(…)` |
| `PeerInfoScreen/PeerInfoScreenCallActions.swift` | 201 | 1 | `peerAvatarCompleteImage(… peer: EnginePeer(peer.peer), …)` → `peerAvatarCompleteImage(… peer: peer.peer, …)` |
| `PeerInfoScreen/PeerInfoScreenCallActions.swift` | 202 | 1 | `text: EnginePeer(peer.peer).displayTitle(…)` → `text: peer.peer.displayTitle(…)` |
| `PeerInfoScreen/PeerInfoScreenCallActions.swift` | 288 | 2 | `.secondLineWithValue(EnginePeer(peer.peer).displayTitle(…))` and `peerAvatarCompleteImage(… peer: EnginePeer(peer.peer), …)` |
| `ChatListUI/ChatListSearchListPaneNode.swift` | 1075 | 2 | `peer: .peer(peer: EnginePeer(peer.peer), chatPeer: EnginePeer(peer.peer))` |
| `ChatListUI/ChatListSearchListPaneNode.swift` | 1076 | 1 | `interaction.peerSelected(EnginePeer(peer.peer), nil, nil, nil, false)` |
| `ChatListUI/ChatListSearchListPaneNode.swift` | 1078 | 1 | `interaction.disabledPeerSelected(EnginePeer(peer.peer), nil, …)` |
| `ChatListUI/ChatListSearchListPaneNode.swift` | 1081 | 1 | `peerContextAction(EnginePeer(peer.peer), .search(nil), node, gesture, location)` |
| `ChatListUI/ChatListSearchListPaneNode.swift` | 3088 | 1 | `filteredPeer(EnginePeer(peer.peer), EnginePeer(accountPeer))` (only the FoundPeer wrap drops; the `EnginePeer(accountPeer)` wrap stays — `accountPeer` is a raw Peer) |
| `ChatListUI/ChatListSearchListPaneNode.swift` | 3096 | 1 | same pattern as 3088 |
| `ChatListUI/ChatListSearchListPaneNode.swift` | 3214 | 1 | same pattern as 3088 |
| `ChatListUI/ChatListSearchListPaneNode.swift` | 3216 | 1 | `entries.append(.localPeer(EnginePeer(peer.peer), …))` |
| `ChatListUI/ChatListSearchListPaneNode.swift` | 3241 | 1 | same pattern as 3088 |
| `TelegramCallsUI/VideoChatScreenMoreMenu.swift` | 171 | 2 | `.secondLineWithValue(EnginePeer(peer.peer).displayTitle(…))` and `peerAvatarCompleteImage(… peer: EnginePeer(peer.peer), …)` |
| `TelegramCallsUI/VideoChatScreenMoreMenu.swift` | 658 | 1 | `peerAvatarCompleteImage(… peer: EnginePeer(peer.peer), …)` |
| `TelegramCallsUI/VideoChatScreenMoreMenu.swift` | 679 | 1 | `text: EnginePeer(peer.peer).displayTitle(…)` |
| **Total** | | **22** | |
Note: only the inner `EnginePeer(peer.peer)` is dropped. Adjacent `EnginePeer(<other>)` wraps (e.g., `EnginePeer(accountPeer)` at lines 3088/3096/3214/3241) are unrelated to this wave and remain.
### Total semantic-edit count
- §1 (TelegramCore): struct (3 lines) + 6 filter rewrites + 4 constructor wraps = ~13 spot edits in one file
- §2 C2: 30 consumer-site downcast rewrites
- §2 C4: 5 consumer-site constructor edits (4 bridge-drops + 1 wrap)
- §2 C3: 22 consumer-site `EnginePeer(peer.peer)` wrap drops
**Total: ~70 semantic edits** across 1 TelegramCore file + 7 consumer files. Type-name mentions in signal/collection signatures need no edit; the type continues to compile.
## Verification
- **Build:** `source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 --configuration=debug_sim_arm64 --continueOnError`
- **Expected outcome:** first-pass-clean build. Errors that surface most likely indicate (a) a missed C2 site, (b) a FoundPeer field-access I missed in the inventory, or (c) a downstream API receiving `peer.peer` that requires raw `Peer` (would need a `._asPeer()` bridge added).
- **Post-build grep validations:**
- `grep -rn "FoundPeer(peer:.*\._asPeer()" submodules/` → expect zero hits in production code (the 4 bridge-drops succeeded).
- `grep -nE "peer\.peer\s+(as\?|is)\s+Telegram" <touched-files>` → expect zero hits in the 7 touched consumer files (FoundPeer-relevant downcasts all rewritten). Other unrelated `something_else.peer.peer as?` patterns may remain on `RenderedPeer` etc.
- `grep -rn "EnginePeer(peer\.peer)" submodules/ --include="*.swift" | grep -v "^submodules/TelegramCore/"` → expect zero hits in the 7 touched consumer files (other files keep their wraps because their `peer` is non-FoundPeer).
## Risks and mitigations
- **Misnamed enum case bindings (C2).** A wrong binding name (e.g. `if case let .channel(c) = peer.peer` then accessing `channel.info`) compiles but is a typo. *Mitigation:* the rewrites are mechanical and each table-row in §2 above shows the exact target form. Each binding is reused inside the same `if case let` clause.
- **Hidden field accesses missed by the inventory.** *Mitigation:* `--continueOnError` build catches everything in one pass. If 5+ unexpected error sites surface, abandon and re-inventory. If only 1–2 surface, fix in place.
- **Downstream APIs requiring raw `Peer`.** Some consumer code may pass `foundPeer.peer` to a function taking the `Peer` protocol. Inventory found 2 such sites already simplified (C3), but unknown sites may exist. *Mitigation:* if surfaced by build errors, bridge with `._asPeer()` at the call site (acceptable transitional pattern — these become next-wave candidates for downstream migration).
- **Equatable behavior change.** `Peer.isEqual(_:)` is the protocol's polymorphic identity test; `EnginePeer.==` is the synthesized-or-manual enum equality. *Mitigation:* `EnginePeer.==` is the canonical equality on the enum and is used throughout the engine codebase. The two should agree on identity-relevant fields (peer id, namespace), and FoundPeer equality is used in `Equatable` set/array dedup contexts where both forms produce the same answer for distinct peers. If tests existed, this would be the place to add one — they don't, so we accept the substitution.
## Out-of-scope cleanups (for future waves)
- The downstream `peerAvatarCompleteImage(account:peer:size:)` in `PeerInfoScreenCallActions.swift:202` accepts `EnginePeer` — no change needed there.
- Wave 33's 5th `._asPeer()` bridge (the one not at a `FoundPeer` constructor) remains. It is at a different downstream API — separate wave.
- `SendAsPeer`, `makePeerInfoController`, `makeChatRecentActionsController`, `makeChatQrCodeScreen` migrations — each is its own wave, larger blast radius.

158
docs/superpowers/specs/2026-04-24-makePeerInfoController-engine-peer-migration-design.md
View file

@ -1,158 +0,0 @@
# Wave 39 — `makePeerInfoController` peer: Peer → EnginePeer migration
Date: 2026-04-24
## Context
Ring-2 cleanup of the `AccountContext` Peer-typed-API surface. Waves 34 (FoundPeer.peer), 35 (SendAsPeer.peer), 36 (ContactListPeer.peer), 37 (peerTokenTitle), and 38 (canSendMessagesToPeer) migrated adjacent Peer-typed APIs to `EnginePeer`. `makePeerInfoController` is the largest remaining Peer-typed-API surface on `AccountContext` and a natural follow-up.
Scope: only `makePeerInfoController` this wave. The sibling methods `makeChatQrCodeScreen` (4 consumer sites) and `makeChatRecentActionsController` (3 consumer sites) are deferred to a trivial follow-up wave.
## Signature change
`AccountContext` protocol declaration (`submodules/AccountContext/Sources/AccountContext.swift:1371`) and its `SharedAccountContextImpl` implementation (`submodules/TelegramUI/Sources/SharedAccountContext.swift:1937`):
```swift
// before
func makePeerInfoController(
context: AccountContext,
updatedPresentationData: (initial: PresentationData, signal: Signal<PresentationData, NoError>)?,
peer: Peer,
mode: PeerInfoControllerMode,
avatarInitiallyExpanded: Bool,
fromChat: Bool,
requestsContext: PeerInvitationImportersContext?
) -> ViewController?
// after
func makePeerInfoController(
context: AccountContext,
updatedPresentationData: (initial: PresentationData, signal: Signal<PresentationData, NoError>)?,
peer: EnginePeer,
mode: PeerInfoControllerMode,
avatarInitiallyExpanded: Bool,
fromChat: Bool,
requestsContext: PeerInvitationImportersContext?
) -> ViewController?
```
Implementation body adds `let peer = peer._asPeer()` shadow at body-top. `peerInfoControllerImpl` (private, same file) and all downstream Peer-typed helpers keep raw `Peer` — out of scope for this wave.
```swift
public func makePeerInfoController(... peer: EnginePeer ...) -> ViewController? {
let peer = peer._asPeer()
let controller = peerInfoControllerImpl(context: context, updatedPresentationData: updatedPresentationData, peer: peer, mode: mode, avatarInitiallyExpanded: avatarInitiallyExpanded, isOpenedFromChat: fromChat)
controller?.navigationPresentation = .modalInLargeLayout
return controller
}
```
## Consumer-side changes
**73 total consumer call sites** (75 raw occurrences minus 1 protocol declaration and 1 implementation). Classification (confirmed via full-repo grep):
- **58 Shape-A** — inline `peer: x._asPeer()` drops to `peer: x`. Mechanical edits.
- **3 Shape-A-variant** — `SettingsSearchableItems.swift` lines 1023, 1049, 1083. The upstream `guard let peer = peer?._asPeer() else` changes to `guard let peer = peer else`, making the local `peer` stay `EnginePeer`. The call-site line does not change.
- **12 Shape-C** — raw Peer local, add `EnginePeer(...)` wrap at call site.
### Shape-C site list
| File | Line | Current peer argument | New |
|---|---|---|---|
| `submodules/SettingsUI/Sources/Privacy and Security/BlockedPeersController.swift` | 270 | `peer: peer` | `peer: EnginePeer(peer)` |
| `submodules/PeerInfoUI/Sources/ChannelMembersController.swift` | 707 | `peer: participant.peer` | `peer: EnginePeer(participant.peer)` |
| `submodules/PeerInfoUI/Sources/ChannelBlacklistController.swift` | 381 | `peer: participant.peer` | `peer: EnginePeer(participant.peer)` |
| `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsControllerNode.swift` | 1011 | `peer: peer` | `peer: EnginePeer(peer)` |
| `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoScreen.swift` | 4306 | `peer: peer` | `peer: EnginePeer(peer)` |
| `submodules/TelegramUI/Sources/Chat/ChatControllerNavigationButtonAction.swift` | 441 | `peer: peer` | `peer: EnginePeer(peer)` |
| `submodules/TelegramUI/Sources/Chat/ChatControllerNavigationButtonAction.swift` | 461 | `peer: peer` | `peer: EnginePeer(peer)` |
| `submodules/TelegramUI/Sources/Chat/ChatControllerNavigationButtonAction.swift` | 471 | `peer: peer` | `peer: EnginePeer(peer)` |
| `submodules/TelegramUI/Sources/Chat/ChatControllerNavigationButtonAction.swift` | 492 | `peer: channel` | `peer: EnginePeer(channel)` |
| `submodules/TelegramUI/Sources/Chat/ChatControllerOpenPeer.swift` | 218 | `peer: peer` | `peer: EnginePeer(peer)` |
| `submodules/TelegramUI/Sources/Chat/ChatControllerOpenPeer.swift` | 359 | `peer: peer` | `peer: EnginePeer(peer)` |
| `submodules/TelegramUI/Sources/Chat/ChatControllerLoadDisplayNode.swift` | 4362 | `peer: peer` | `peer: EnginePeer(peer)` |
Each Shape-C wrap is a future-wave drop candidate once the raw-Peer source (stored field, `participant.peer`, `renderedPeer.chatMainPeer`, etc.) migrates upstream.
### Shape-A-variant detail
`SettingsSearchableItems.swift` three sites share the same structure:
```swift
// before
let _ = (context.engine.data.get(TelegramEngine.EngineData.Item.Peer.Peer(id: context.account.peerId))
|> deliverOnMainQueue).start(next: { peer in // peer: EnginePeer?
guard let peer = peer?._asPeer() else { // peer: Peer (shadowed)
return
}
let controller = context.sharedContext.makePeerInfoController(
context: context,
updatedPresentationData: nil,
peer: peer,
mode: .myProfile,
...
)
...
})
// after
let _ = (context.engine.data.get(TelegramEngine.EngineData.Item.Peer.Peer(id: context.account.peerId))
|> deliverOnMainQueue).start(next: { peer in // peer: EnginePeer?
guard let peer = peer else { // peer: EnginePeer (shadowed)
return
}
let controller = context.sharedContext.makePeerInfoController(
context: context,
updatedPresentationData: nil,
peer: peer,
mode: .myProfile,
...
)
...
})
```
## Files touched (≈50)
Inventoried from the grep output. Not exhaustive here; per-site enumeration lives in the implementation plan.
Signature files: `AccountContext/Sources/AccountContext.swift`, `TelegramUI/Sources/SharedAccountContext.swift`.
Shape-A consumer files (sample, not exhaustive): `SelectivePrivacySettingsPeersController.swift`, `InstantPageControllerNode.swift`, `CallListController.swift`, `ContactsController.swift`, `ContactContextMenus.swift`, `SecureIdAuthController.swift`, `ChannelAdminController.swift`, `ChannelMembersController.swift`, `ChannelBannedMemberController.swift`, `ChannelPermissionsController.swift`, `MessageStatsController.swift`, `GroupStatsController.swift`, `InviteRequestsController.swift`, `BrowserInstantPageContent.swift`, `WebAppController.swift`, `PeersNearbyController.swift`, `ChatSendStarsScreen.swift`, `ChatRecentActionsControllerNode.swift`, `MiniAppListScreen.swift`, `JoinSubjectScreen.swift`, `NewContactScreen.swift`, `StarsTransactionScreen.swift`, `StoryItemSetContainerViewSendMessage.swift`, `StoryItemSetContainerComponent.swift`, `GiftViewScreen.swift`, `GiftOptionsScreen.swift`, `StorageUsageScreen.swift`, `TextProcessingScreen.swift`, `PeerInfoScreen.swift`, `PeerInfoScreenOpenURL.swift`, `JoinAffiliateProgramScreen.swift`, `ChatControllerScrollToPointInHistory.swift`, `OpenUrl.swift`, `OpenResolvedUrl.swift`, `TextLinkHandling.swift`, `ChatController.swift`, `OpenAddContact.swift`, `ChatManagingBotTitlePanelNode.swift`, `NavigateToChatController.swift`, `SharedAccountContext.swift` (3 self-call sites), `OverlayAudioPlayerControllerNode.swift`, `PollResultsController.swift`, `ChatControllerOpenWebApp.swift`, `ChatControllerNavigationButtonAction.swift`, `ChatListController.swift`, `ChatListSearchListPaneNode.swift`.
Shape-A-variant file: `SettingsSearchableItems.swift`.
Shape-C-only files (other than those with mixed shapes above): `BlockedPeersController.swift`, `ChannelBlacklistController.swift`, `ChatControllerOpenPeer.swift`, `ChatControllerLoadDisplayNode.swift`.
## Build/verification plan
1. Apply all edits atomically. Mechanical Edit-tool string replaces for the 58 Shape-A drops; focused Edits for the 3 Shape-A-variants (guard line) and 12 Shape-C wraps.
2. Full project build: `source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 --configuration=debug_sim_arm64 --continueOnError`.
3. Fix any iteration-surfaced errors. Budget 2–4 iterations.
4. Clean build → atomic commit with wave-39 message.
5. Update `project_postbox_refactor_next_wave.md` memory, `docs/superpowers/postbox-refactor-log.md`, and `CLAUDE.md` wave tally.
6. No test runs (project has no unit tests).
## Risks / watch-out
- **Destructure/binding cascades.** Locals named `peer` declared as `Peer` somewhere in a call chain and fed to `makePeerInfoController`. The body-shadow pattern contains divergence at the public API boundary, but transient Swift inference errors may surface at intermediate points.
- **`chatMainPeer` / `renderedPeer.peer` property types.** Shape-C sites at `ChatControllerNavigationButtonAction.swift:441/461/471/492` and `ChatControllerLoadDisplayNode.swift:4362` assume these properties return raw `Peer`. If they already return `EnginePeer` in the current repo (unlikely but possible after earlier waves), the wrap should be `peer: peer` with no wrap. Verify in plan phase.
- **Outflow sites in Shape-C files.** Some Shape-C files may have additional `peer: Peer` flows elsewhere that are unrelated to this wave. Do not chase — only touch the listed sites.
## Abandonment criteria
- Iteration count exceeds 5.
- A cascade requires editing `peerInfoControllerImpl` (violates body-shadow boundary).
- Any non-consumer file (e.g., anything in `TelegramCore`, `Postbox`, `TelegramApi`) surfaces an error.
## Net effect
- Public API: `AccountContext.makePeerInfoController` takes `EnginePeer` instead of raw `Peer`.
- Bridges: -58 inline `_asPeer()` + -3 upstream-guard `_asPeer()` + 12 new `EnginePeer(...)` wraps = **net -49 bridges**.
- Ratchet: 12 Shape-C wraps become future-wave drop candidates (e.g., `RenderedPeer → EngineRenderedPeer` migration, participant-object migrations).
## Out of scope
- `makeChatQrCodeScreen` (4 sites), `makeChatRecentActionsController` (3 sites) — deferred to a trivial follow-up wave.
- `peerInfoControllerImpl` and downstream Peer-typed helpers.
- Shape-C source migrations (participant objects, `renderedPeer.chatMainPeer`, etc.).

71
docs/superpowers/specs/2026-04-24-peertokentitle-engine-peer-migration-design.md
View file

@ -1,71 +0,0 @@
---
title: "Postbox → TelegramEngine wave 37: peerTokenTitle peer parameter Peer → EnginePeer"
date: 2026-04-24
status: draft
---
# Wave 37 design — `peerTokenTitle` peer parameter Peer → EnginePeer
## Context
Wave 36 (commit `069a060de1`, squashed into `8408e0ae19`) migrated `ContactListPeer.peer` from `Peer` to `EnginePeer` and added two new `peer._asPeer()` bridges at `ContactMultiselectionController.swift:386` and `:403`, feeding the private free function `peerTokenTitle(accountPeerId: PeerId, peer: Peer, ...)` at `:21`.
Wave 37 migrates `peerTokenTitle`'s `peer` parameter so those two new bridges — plus three older bridges at `:171`, `:201`, and `:748` — can all drop to zero in one atomic commit. This is a ring-2 cleanup: it consumes bridges that prior waves installed.
## Scope
All changes are confined to `submodules/TelegramUI/Sources/ContactMultiselectionController.swift`.
### Changes
| Location | Before | After |
|---|---|---|
| L21 | `peer: Peer` | `peer: EnginePeer` |
| L27 | `EnginePeer(peer).displayTitle(strings: strings, displayOrder: nameDisplayOrder)` | `peer.displayTitle(strings: strings, displayOrder: nameDisplayOrder)` |
| L171 | `peer: peer._asPeer()` | `peer: peer` |
| L201 | `peer: peer._asPeer()` | `peer: peer` |
| L386 | `peer: peer._asPeer()` | `peer: peer` |
| L403 | `peer: peer._asPeer()` | `peer: peer` |
| L748 | `peer: peer._asPeer()` | `peer: peer` |
All 5 call-site bindings `peer` are already `EnginePeer` at the call site — verified by the existing `._asPeer()` bridge.
The function body at L22–L28 stays semantically identical: `peer.id`, `peer.id.isReplies`, and `EnginePeer.displayTitle(strings:displayOrder:)` are all available on `EnginePeer`.
### Intentionally out of scope
- **`accountPeerId: PeerId`** — `PeerId` is already typealiased to `EnginePeer.Id`; not a Postbox-type leak.
- **`import Postbox` at L5** — other parts of the file still use Postbox-typed APIs (e.g., `.peer(peer: Peer, ...)` at L459 feeding the `SelectedPeer` enum). File-level Postbox-free is a later wave.
- **L459's `peer._asPeer()`** — feeds a different, not-yet-migrated Peer-typed API (`SelectedPeer.peer(peer: Peer, ...)`), outside this wave.
- **Other callers** — `peerTokenTitle` is `private` to this file; a full-codebase grep confirmed zero external call sites.
## Verification
1. **Pre-build grep** — confirm zero remaining `peerTokenTitle(.*_asPeer())` matches in the file and the broader codebase.
2. **Single full project build** via `Make.py` with `--continueOnError`. Expected first-pass-clean.
3. **Post-build grep** — same `peerTokenTitle(.*_asPeer())` pattern should remain empty.
## Risk
**Very low.** Private free function, single file, fully self-contained, all call sites mechanical bridge drops. No public-API change, no BUILD-file touch, no other modules affected.
Expected outcome: first-pass-clean build. Good reset after wave 36's 6-iteration convergence.
## Commit message
```
Postbox → TelegramEngine wave 37
peerTokenTitle: peer parameter Peer → EnginePeer.
Drops 5 _asPeer() bridges in ContactMultiselectionController.swift
(L171, L201, L386, L403, L748) — bridges installed by prior waves.
Private free function, single-file change.
```
## References
- CLAUDE.md — "Postbox → TelegramEngine refactor (in progress)"
- `docs/superpowers/postbox-refactor-log.md` — wave history
- Memory `project_postbox_refactor_next_wave.md` — wave-37 candidate list

187
docs/superpowers/specs/2026-04-24-rcp-peers-engine-migration-design.md
View file

@ -1,187 +0,0 @@
# Wave 44 — `RenderedChannelParticipant.peers: [PeerId: Peer] → [EnginePeer.Id: EnginePeer]`
**Date:** 2026-04-24
**Status:** Approved, pending plan
**Predecessor:** Wave 41 (commit `32573c9808`) migrated `RenderedChannelParticipant.peer` from `Peer` to `EnginePeer` and installed ADD-WRAP markers at consumer-side read sites that this wave drops.
**Goal:** Close out the wave-41 ratchet by migrating the sibling `peers: [PeerId: Peer]` field to `[EnginePeer.Id: EnginePeer]`. After this wave, `RenderedChannelParticipant` has no raw `Peer` types in its public surface.
## Context
`RenderedChannelParticipant` is declared in `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelParticipants.swift`:
```swift
public struct RenderedChannelParticipant: Equatable {
public let participant: ChannelParticipant
public let peer: EnginePeer // migrated in wave 41
public let peers: [PeerId: Peer] // target of this wave
public let presences: [PeerId: PeerPresence] // out of scope (PeerPresence is Postbox protocol)
public init(participant: ChannelParticipant, peer: EnginePeer, peers: [PeerId: Peer] = [:], presences: [PeerId: PeerPresence] = [:]) { ... }
}
```
`peers` is a supplementary dict of "referenced peers" (e.g. the admin who promoted this member, the admin who banned them). Consumers use it to render relationships — never with `as?`/`is` casts, only `.id` and `.displayTitle(...)` on extracted values.
## Migration target
- `peers: [PeerId: Peer]` → `peers: [EnginePeer.Id: EnginePeer]`
- init default: `[:]` on both sides (type changes transparently)
- `presences` field stays unchanged.
## Scope
### Declaration (1 file, 2 edits)
**`submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelParticipants.swift`**
- Line 11: `public let peers: [PeerId: Peer]` → `public let peers: [EnginePeer.Id: EnginePeer]`
- Line 14: `peers: [PeerId: Peer] = [:]` → `peers: [EnginePeer.Id: EnginePeer] = [:]`
### TelegramCore producer sites (8 files, 8 construction sites, ~16 edits)
All 8 producers follow the identical pattern of building a local `peers: [PeerId: Peer] = [:]` dict inside a `postbox.transaction` and passing it to an `RCP(peers: peers, ...)` constructor. Per-site edits: change local dict type, wrap each insertion value with `EnginePeer(...)`.
| File | `var peers:` decl | `peers[X.id] = X` insertions | RCP construction |
|---|---|---|---|
| `TelegramEngine/Messages/RequestStartBot.swift` | line 61 | line 64 | line 65 |
| `TelegramEngine/Peers/ChannelOwnershipTransfer.swift` | line 170 | lines 172, 176 | line 180 (2 RCP constructions share `peers`) |
| `TelegramEngine/Peers/JoinChannel.swift` | line 59 | lines 64, 77 | line 82 |
| `TelegramEngine/Peers/AddPeerMember.swift` | line 242 | lines 244, 251 | line 255 |
| `TelegramEngine/Peers/PeerAdmins.swift` | line 251 | lines 253, 259 | line 262 |
| `TelegramEngine/Peers/ChannelBlacklist.swift` | line 128 | lines 130, 136 | line 140 |
| `TelegramEngine/Peers/Ranks.swift` | line 60 | lines 62, 68 | line 95 |
| `TelegramEngine/Peers/ChannelMembers.swift` | line 102 | line 105 | line 115 |
**Per-site rewrite:**
```swift
// before
var peers: [PeerId: Peer] = [:]
peers[peer.id] = peer
// after
var peers: [EnginePeer.Id: EnginePeer] = [:]
peers[peer.id] = EnginePeer(peer)
```
### Consumer-side DROPs: `.mapValues({ $0._asPeer() })` transforms (5 sites)
These consumer-side constructors start from a `[PeerId: EnginePeer]` source dict and currently unwrap to `[PeerId: Peer]` to feed into the RCP constructor. After migration, the unwrap transform is a no-op and can be dropped.
| File | Line | Before → after |
|---|---|---|
| `PeerInfoUI/Sources/ChannelAdminsController.swift` | 926 | `peers: peers.mapValues({ $0._asPeer() })` → `peers: peers` |
| `PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift` | 994 | same |
| `PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift` | 998 | same |
| `PeerInfoUI/Sources/ChannelMembersSearchControllerNode.swift` | 409 | same |
| `PeerInfoUI/Sources/ChannelMembersSearchControllerNode.swift` | 413 | same |
**Verification required at plan time:** for each of these 5 sites, grep back up in the enclosing function to confirm the local `peers` variable is declared `[PeerId: EnginePeer]` (the source of the mapValues transform). If any of the sources turn out to be `[PeerId: Peer]` rather than `[PeerId: EnginePeer]`, that site's transform is NOT a no-op and instead becomes a wrap (`.mapValues(EnginePeer.init)`) — still a net-zero or gain depending on where the source originates.
### Consumer-side DROPs: `EnginePeer(peer).displayTitle(...)` wraps (6 sites)
These are the wave-41 ADD-WRAP markers. Pattern: extract `peer` from `participant.peers[X]`, wrap with `EnginePeer(peer)` to call `.displayTitle(...)`. After migration, `peer` is already `EnginePeer` — drop the wrap.
| File | Line | Pattern |
|---|---|---|
| `PeerInfoUI/Sources/ChannelAdminsController.swift` | 297 | `EnginePeer(peer).displayTitle(strings: strings, ...)` → `peer.displayTitle(strings: strings, ...)` |
| `PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift` | 839 | same |
| `PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift` | 870 | same |
| `PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift` | 1091 | same |
| `PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift` | 1122 | same |
| `PeerInfoUI/Sources/ChannelBlacklistController.swift` | 165 | same |
The adjacent `peer.id == participant.peer.id` comparisons are unchanged: both sides are `EnginePeer.Id` (already a typealias of `PeerId`).
### Consumer-side ADD-UNWRAP (1 site)
**`submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsHistoryTransition.swift`**, lines 672–674:
```swift
for (_, peer) in participant.peers {
peers[peer.id] = peer // `peers` is SimpleDictionary<PeerId, Peer>
}
```
After migration `peer` is `EnginePeer`; the outer `peers` SimpleDictionary is still `[PeerId: Peer]`. Rewrite:
```swift
for (_, peer) in participant.peers {
peers[peer.id] = peer._asPeer()
}
```
### Constructor sites with no `peers:` arg — no change (12 sites)
Default value's *type* changes (`[PeerId: Peer] = [:]` → `[EnginePeer.Id: EnginePeer] = [:]`) but the literal `[:]` works for either. These sites compile unchanged:
- TelegramCore: `ChannelAdminEventLogs.swift:271, 279` (x2), `:287` (x2), `:483` (x2) — 7 constructions
- `PeerInfoUI/.../ChannelAdminsController.swift:921`
- `PeerInfoUI/.../ChannelMembersSearchContainerNode.swift:987`
- `PeerInfoUI/.../ChannelMembersSearchControllerNode.swift:404`
- `TelegramUI/.../ChatRecentActionsController/.../ChatRecentActionsFilterController.swift:445`
- `TelegramUI/.../ChatControllerAdminBanUsers.swift:224, :370, :755` (3 constructions)
- `TelegramUI/.../StoryContainerScreen/.../StoryContentLiveChatComponent.swift:361`
## Net impact
**Consumer-surface bridges:** −6 wraps + −5 unwrap transforms + +1 unwrap = **−10 bridges**.
**TelegramCore-internal bridges:** +~12 wraps (`EnginePeer(peer)` at producer insertion points, inside `import Postbox` modules). These do not regress Postbox-hygiene since every producer file already imports Postbox.
**Structural:** `RenderedChannelParticipant` public surface contains no raw `Peer` types after this wave (only `ChannelParticipant`, `EnginePeer`, `[EnginePeer.Id: EnginePeer]`, `[PeerId: PeerPresence]`). `presences` still leaks `PeerPresence` — separate future migration.
## Iteration budget
**2–3 iterations** (wave-41 foundational-type lesson: field migrations on passed-around structs budget 2–4 iterations, not first-pass-clean).
Verified absence of hidden grep surface:
- No `as?` / `is TelegramX` casts on `participant.peers[X]` extractions (grepped).
- No Peer-only properties accessed on extractions (uses `.id` and `.displayTitle(...)` only — both EnginePeer-forwarded).
- All 8 TelegramCore producers build locally (verified) — no chain-migration.
## Risks
1. **Producer local-dict migration under `continueOnError`.** If a producer builds the dict with more than two insertions and misses one, the build flags mismatched dict-value types. Low blast radius (per-file local).
2. **Hidden consumer site.** If a grep miss surfaces a `participant.peers` site not enumerated here, the wrap/unwrap balance changes. Mitigation: plan document must re-run the narrow grep (`participant\.peers|rcp\.peers|renderedParticipant\.peers`) at plan-write time and iteration-0 time.
3. **mapValues source-dict check.** If any of the 5 consumer-side `.mapValues({ $0._asPeer() })` sites has a source `[PeerId: Peer]` (not `[PeerId: EnginePeer]`), the migration at that site inverts (becomes a wrap instead of a drop). Plan-time per-site verification required.
4. **SimpleDictionary import.** The one ADD-UNWRAP site in `ChatRecentActionsHistoryTransition.swift` already uses `SimpleDictionary<PeerId, Peer>` — no new Postbox exposure.
## Out of scope
- `RenderedChannelParticipant.presences: [PeerId: PeerPresence]` — `PeerPresence` is a Postbox protocol; separate migration with different shape.
- `RenderedPeer → EngineRenderedPeer` foundational-type migration (listed in wave-44 memo as candidate 6; save for a dedicated session).
- `PeerInfoHeader*` bundle (wave-44 memo candidate 1) — considered but not selected for wave 44; candidate for wave 45.
## Success criteria
1. `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelParticipants.swift` has `peers: [EnginePeer.Id: EnginePeer]` declaration.
2. All 8 TelegramCore producers compile with wrapped inserts.
3. All 5 consumer `.mapValues({ $0._asPeer() })` transforms are removed.
4. All 6 consumer `EnginePeer(peer).displayTitle(...)` wraps on extracted dict values are removed (`peer.displayTitle(...)`).
5. `ChatRecentActionsHistoryTransition.swift:673` uses `peer._asPeer()` for the SimpleDictionary insertion value.
6. Full `Telegram/Telegram` build (`configuration=debug_sim_arm64`) is clean — **one** atomic commit.
7. Grep post-migration: `participant\.peers\[` returns only engine-typed call sites; no residual `EnginePeer(peer)` on `.peers[...]` extractions.
## Commit message template
```
Postbox -> TelegramEngine wave 44
Migrate RenderedChannelParticipant.peers from [PeerId: Peer] to
[EnginePeer.Id: EnginePeer]. Closes the wave-41 ratchet — the public
struct no longer leaks raw Peer types in any field (presences stays
Postbox-typed; separate migration).
Consumer-surface: -10 bridges (6 EnginePeer(peer) wraps dropped at
read sites, 5 .mapValues({ $0._asPeer() }) transforms dropped at
constructor sites, 1 ._asPeer() added at
ChatRecentActionsHistoryTransition.swift:673 where the value is
inserted into a raw-Peer SimpleDictionary).
TelegramCore producers: 8 files, each builds a local
[EnginePeer.Id: EnginePeer] dict from transaction.getPeer() wrapping
at the insertion point.
No unit tests in this project; full Telegram/Telegram build verified
under configuration=debug_sim_arm64.
```

175
docs/superpowers/specs/2026-04-24-renderedchannelparticipant-peer-engine-peer-migration-design.md
View file

@ -1,175 +0,0 @@
# Wave 41 — `RenderedChannelParticipant.peer: Peer → EnginePeer` migration — Design
**Date:** 2026-04-24
**Wave:** 41
**Status:** spec
## Goal
Migrate the `peer` field of `TelegramCore.RenderedChannelParticipant` from the Postbox protocol `Peer` to the TelegramCore enum `EnginePeer`. All construction sites and consumer accesses are updated in one atomic commit.
## Motivation
- Drops 2 Shape-C `EnginePeer(participant.peer)` wraps installed by wave 39 (`ChannelMembersController.swift:707`, `ChannelBlacklistController.swift:381`).
- Drops ~37 additional `EnginePeer(...)` / `._asPeer()` bridges across the consumer surface (total ~39 bridge drops after counting `EnginePeer(peer.peer).compactDisplayTitle` sites in `AdminUserActionsSheet.swift`).
- Aligns `RenderedChannelParticipant.peer` with the pattern established for `FoundPeer.peer` (wave 34), `SendAsPeer.peer` (wave 35), `ContactListPeer.peer` (wave 36), and all `AccountContext.makeX(peer: ...)` facades (waves 37–40).
- Ratchet candidate for future waves: once `.peer` is `EnginePeer`, the `peers: [PeerId: Peer]` dict field becomes the only Postbox-typed field on the struct — a follow-up wave can migrate `peers: [EnginePeer.Id: EnginePeer]` in isolation.
## Scope
### In scope
**TelegramCore:**
- `submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelParticipants.swift` — change struct field + init param + Equatable impl
- 9 TelegramCore files containing 16 construction sites where `RenderedChannelParticipant(... peer: peer, ...)` is called with a raw `Peer` from `transaction.getPeer()` — wrap with `EnginePeer(peer)`:
- `Messages/RequestStartBot.swift:65`
- `Peers/AddPeerMember.swift:255`
- `Peers/ChannelAdminEventLogs.swift:271, 279, 287, 483` (7 constructor calls total)
- `Peers/ChannelBlacklist.swift:140`
- `Peers/ChannelMembers.swift:115`
- `Peers/ChannelOwnershipTransfer.swift:180` (2 constructor calls)
- `Peers/JoinChannel.swift:82`
- `Peers/PeerAdmins.swift:262`
- `Peers/Ranks.swift:95`
**Consumer (17 files):** all sites accessing `participant.peer` or constructing `RenderedChannelParticipant`:
- `submodules/PeerInfoUI/Sources/ChannelAdminsController.swift`
- `submodules/PeerInfoUI/Sources/ChannelBlacklistController.swift`
- `submodules/PeerInfoUI/Sources/ChannelMembersController.swift`
- `submodules/PeerInfoUI/Sources/ChannelMembersSearchContainerNode.swift`
- `submodules/PeerInfoUI/Sources/ChannelMembersSearchControllerNode.swift`
- `submodules/PeerInfoUI/Sources/ChannelPermissionsController.swift`
- `submodules/SearchPeerMembers/Sources/SearchPeerMembers.swift`
- `submodules/TelegramUI/Components/AdminUserActionsSheet/Sources/AdminUserActionsSheet.swift`
- `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsController.swift`
- `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsFilterController.swift`
- `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/ChatRecentActionsHistoryTransition.swift`
- `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/PeerInfoMembers.swift`
- `submodules/TelegramUI/Components/ShareWithPeersScreen/Sources/ShareWithPeersScreenState.swift`
- `submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryContentLiveChatComponent.swift`
- `submodules/TelegramUI/Sources/ChatControllerAdminBanUsers.swift`
- `submodules/TemporaryCachedPeerDataManager/Sources/ChannelMemberCategoryListContext.swift`
- `submodules/TemporaryCachedPeerDataManager/Sources/PeerChannelMemberCategoriesContextsManager.swift`
### Out of scope (deferred)
- `RenderedChannelParticipant.peers: [PeerId: Peer]` — still `[PeerId: Peer]` dict. Not migrated this wave.
- `RenderedChannelParticipant.presences: [PeerId: PeerPresence]` — still `[PeerId: PeerPresence]` dict. Not migrated this wave.
- `PeerInfoScreenData.peer → EnginePeer` — future wave 42 candidate (drops 2 wave-40 wraps).
- `RenderedPeer → EngineRenderedPeer` — future major wave; saved for a dedicated session.
- `PeerInfoMember.peer: Peer` enum accessor in `PeerInfoMembers.swift:30-39` — retained as `Peer` for this wave (contained by a single `._asPeer()` inside the `.channelMember` branch). Migration of this accessor is a separate follow-up.
## Design
### Struct change
```swift
// submodules/TelegramCore/Sources/TelegramEngine/Peers/ChannelParticipants.swift
public struct RenderedChannelParticipant: Equatable {
public let participant: ChannelParticipant
public let peer: EnginePeer // ← was: Peer
public let peers: [PeerId: Peer] // unchanged
public let presences: [PeerId: PeerPresence] // unchanged
public init(participant: ChannelParticipant, peer: EnginePeer, peers: [PeerId: Peer] = [:], presences: [PeerId: PeerPresence] = [:]) {
self.participant = participant
self.peer = peer
self.peers = peers
self.presences = presences
}
public static func ==(lhs: RenderedChannelParticipant, rhs: RenderedChannelParticipant) -> Bool {
return lhs.participant == rhs.participant && lhs.peer == rhs.peer // ← was: lhs.peer.isEqual(rhs.peer)
}
}
```
`EnginePeer` is `Equatable` by enum synthesis (verified — each associated value type is Equatable: `TelegramUser`, `TelegramGroup`, `TelegramChannel`, `TelegramSecretChat`). `==` becomes cleaner.
### Consumer-site shapes
Per the pre-flight classification, sites fall into these shapes:
- **ZERO** (transparent) — `.id`, `.isDeleted`, `.indexName`, `.addressName`, `.compactDisplayTitle`, `.displayTitle(strings:displayOrder:)`, `.displayLetters`, `.debugDisplayTitle`, etc. All exposed on `EnginePeer`. ~160 sites. **No edit.**
- **DROP** — `EnginePeer(participant.peer)` → `participant.peer`. ~32 consumer sites + 2 `.peer._asPeer()` downgrades that also drop. The biggest class of edits. Key sites:
- `ChannelAdminsController.swift:326, 921, 926` (921, 926 drop `._asPeer()` from constructor)
- `ChannelBlacklistController.swift:170, 381`
- `ChannelMembersController.swift:334, 707`
- `ChannelMembersSearchContainerNode.swift:212 (×2), 223`
- `ChannelMembersSearchControllerNode.swift:148`
- `ChannelPermissionsController.swift:480, 483`
- `SearchPeerMembers.swift:30, 36, 61, 76`
- `ChatRecentActionsController.swift:359`
- `ChatRecentActionsFilterController.swift:217`
- `ChatRecentActionsHistoryTransition.swift:719, 730, 740, 828, 842, 870, 943, 955, 973, 990, 1026` (one `EnginePeer(new.peer)` drop per site)
- `ShareWithPeersScreenState.swift:558, 576`
- `AdminUserActionsSheet.swift:284, 404, 416, 417, 522, 523` (EnginePeer(peer.peer) wraps)
- `StoryContentLiveChatComponent.swift:370` (drops `._asPeer()`)
- `ChatControllerAdminBanUsers.swift:372, 757` (drops `._asPeer()`)
- **CAST** — `if let user = participant.peer as? TelegramUser, user.botInfo != nil` → `if case let .user(user) = participant.peer, user.botInfo != nil`. 9 sites across 4 files:
- `ChannelMembersController.swift:305`
- `ChannelMembersSearchContainerNode.swift:752, 884, 1052, 1136`
- `ChannelMembersSearchControllerNode.swift:516, 558`
- `ShareWithPeersScreenState.swift:566`
All 9 follow the identical 2-clause pattern (`as? TelegramUser`, `user.botInfo != nil`). Pattern-match rewrite is mechanically safe.
- **ADD-ASPEER** — site needs raw `Peer`. 3 sites:
- `ChatRecentActionsHistoryTransition.swift:675` — `peers[participant.peer.id] = participant.peer` → `peers[participant.peer.id] = participant.peer._asPeer()` (assigning into `SimpleDictionary<PeerId, Peer>`).
- `ChatRecentActionsHistoryTransition.swift:2275` — same pattern.
- `PeerInfoMembers.swift:33` — `return participant.peer` → `return participant.peer._asPeer()` (outer enum accessor returns `Peer`; deliberately contained — migration of `PeerInfoMember.peer` deferred).
- **ADD-WRAP** — consumer construction site where the local is raw `Peer` but the field is now `EnginePeer`. 7 sites across 3 files:
- `ChannelMembersSearchContainerNode.swift:987, 994, 998` — `peer: peer` where `peer = peerView.peers[participant.peerId]` is raw `Peer`. → `peer: EnginePeer(peer)`.
- `ChannelMembersSearchControllerNode.swift:404, 409, 413` — same pattern.
- `ChatRecentActionsFilterController.swift:445` — `peer: user` where `user: TelegramUser` (from `case let .user(user) = peer`). → `peer: .user(user)` or `peer: EnginePeer(user)`. Use `peer: .user(user)` (direct enum case) for clarity.
- `ChatControllerAdminBanUsers.swift:226` — `peer: peer` where `peer = author: Peer`. → `peer: EnginePeer(peer)`.
### TelegramCore-internal constructor sites
All 16 sites receive a raw `Peer` (from `transaction.getPeer()` / `peers[id]`) and pass it as `peer:`. All become `peer: EnginePeer(peer)`:
```swift
// Before:
RenderedChannelParticipant(participant: participant, peer: peer, peers: peers, presences: presences)
// After:
RenderedChannelParticipant(participant: participant, peer: EnginePeer(peer), peers: peers, presences: presences)
```
No shape-selection judgment required — all 16 sites follow this exact template. The `peers` and `presences` dictionaries are unchanged.
## Risks
- **R1: CAST semantic preservation.** The 9 `as? TelegramUser` sites all gate on `user.botInfo != nil`. Pattern-match rewrite is `if case let .user(user) = participant.peer, user.botInfo != nil`. Verified: `EnginePeer.user(TelegramUser)` gives access to the same `TelegramUser` instance; `.botInfo` is a `TelegramUser` property. Semantically equivalent.
- **R2: `==` implementation change.** The struct's `==` goes from `lhs.peer.isEqual(rhs.peer)` (protocol dispatch) to `lhs.peer == rhs.peer` (synthesized). `EnginePeer.==` uses Swift-synthesized enum equality: each case compares associated values. Each associated-value type (`TelegramUser`, `TelegramGroup`, `TelegramChannel`, `TelegramSecretChat`) is `Equatable` via its own `==` implementation. Semantically equivalent to the protocol `isEqual`.
- **R3: PeerInfoMembers.swift:33 cascade.** `PeerInfoMember.peer: Peer` enum accessor at line 30-39 returns `participant.peer` on the `.channelMember` branch. Fix is a single `._asPeer()`. The outer enum's API stays unchanged — no cascade beyond this file. Future wave can migrate `PeerInfoMember.peer` to `EnginePeer`.
- **R4: Consumer-side constructor sites in ChannelMembersSearch*Node.** 3 sites each in the `Container` and `Controller` node files construct `RenderedChannelParticipant` for the legacy-group search path. The `peer` local is raw `Peer` from `peerView.peers`. Mechanical wrap with `EnginePeer(peer)` at the `peer:` argument.
- **R5: `participant.peers` dict staying `[PeerId: Peer]`.** Current code uses `peers.mapValues({ $0._asPeer() })` at construction sites where the local dict is `[EnginePeer.Id: EnginePeer]`. This pattern is unchanged by the wave — the `peers` field is not being migrated.
- **R6: Hidden consumer sites.** Pre-flight searched: `RenderedChannelParticipant(` constructors across `submodules/`, `participant.peer` access (subagent classification), all files that import TelegramCore/Postbox and reference `RenderedChannelParticipant`. 17 consumer files + 10 TelegramCore files confirmed. Risk of overlooked third-party or sparse consumer: low.
- **R7: Pre-existing WIP contamination.** `git status` shows unrelated WIP: `submodules/TelegramUI/Sources/ChatMessageTransitionNode.swift`, `build-system/bazel-rules/sourcekit-bazel-bsp` submodule marker, several untracked dirs. Wave-39 lesson: enumerate files explicitly in `git add`; run `git status --short` after staging.
## Verification
- Single full Bazel build with `--continueOnError` after all edits (extends wave-39 / wave-40 pattern).
- Expected outcome: **first-pass-clean build** based on wave-39 precedent — 52 files / 73 sites / non-propagating signature migration → first-pass-clean. This wave is comparable scale (27 files / ~200+ sites including ZEROs) with even cleaner mechanics: ZERO sites are literally no edit; DROP/CAST/ADD-WRAP/ADD-ASPEER patterns are all mechanical; no inference-dependent return types.
- Budget: 3–5 iterations if classification is wrong; first-pass-clean if classification is exact.
## Net ratchet economics
- Bridges dropped: ~37–39 (32 consumer DROPs + 2 `._asPeer()` drops in ChannelAdminsController + ~6 `EnginePeer(peer.peer).X` drops in AdminUserActionsSheet, possibly double-counted; final net post-commit grep will settle the number).
- Bridges added: ~23 (16 TelegramCore `EnginePeer(peer)` wraps at constructor call sites + 4 ADD-WRAP consumer constructors + 3 ADD-ASPEER).
- **Net:** ~−14 to −16 bridges. Positive economics even counting TelegramCore-internal adds.
- Ratchet marker: the 4 consumer ADD-WRAP constructor sites (`ChannelMembersSearch*Node` + `ChatControllerAdminBanUsers:226`) are candidates for drop in a future wave that migrates the `peerView.peers[id]` / `authors: [Peer]` upstream flows to EnginePeer.
## Out-of-scope inventory (for the next wave)
If a follow-up wave migrates **`RenderedChannelParticipant.peers: [PeerId: Peer] → [EnginePeer.Id: EnginePeer]`**, the ADD-WRAP sites in this wave (all `peers: peers.mapValues({ $0._asPeer() })`) simplify to `peers: peers`. That's a high-ratchet candidate wave that becomes mechanical once this wave lands.

141
docs/superpowers/specs/2026-04-24-sendaspeer-engine-peer-migration-design.md
View file

@ -1,141 +0,0 @@
# Wave 35 — `SendAsPeer.peer` `Peer` → `EnginePeer`
Date: 2026-04-24
Status: approved design, awaiting plan
Wave shape: Peer-typed-API single atomic commit (wave 34 pattern replayed on a smaller target)
## Goal
Eliminate the Postbox-protocol `Peer` leak in the public `SendAsPeer` struct by migrating its `peer` field from `Peer` to `EnginePeer`. Apply wave 34's lessons — comprehensive pre-flight grep including `.peer as?`/`is` casts, outflow-arg patterns, and loop-body `.peer` accesses — to keep post-commit build iterations low.
## Non-goals
- `ContactListPeer.peer(peer: Peer, ...)` case-payload migration — broader blast radius, deferred.
- `canSendMessagesToPeer(_:)` parameter migration — broader blast radius, deferred.
- `makePeerInfoController` / `makeChatQrCodeScreen` / `makeChatRecentActionsController` protocol-method migrations — broader blast radius, deferred.
- `CachedSendAsPeers` cache entry — already `PeerId`-based, entirely inside TelegramCore; no change needed.
- No new engine wrappers, typealiases, or facades introduced in this wave.
## Type change
```swift
// Before
public struct SendAsPeer: Equatable {
public let peer: Peer // Postbox protocol
public let subscribers: Int32?
public let isPremiumRequired: Bool
public init(peer: Peer, subscribers: Int32?, isPremiumRequired: Bool) { … }
public static func ==(lhs: SendAsPeer, rhs: SendAsPeer) -> Bool {
return lhs.peer.isEqual(rhs.peer) && lhs.subscribers == rhs.subscribers && lhs.isPremiumRequired == rhs.isPremiumRequired
}
}
// After
public struct SendAsPeer: Equatable {
public let peer: EnginePeer // TelegramCore value type
public let subscribers: Int32?
public let isPremiumRequired: Bool
public init(peer: EnginePeer, subscribers: Int32?, isPremiumRequired: Bool) { … }
// Equatable synthesized — EnginePeer is Equatable.
}
```
## In-scope files
### Category α — TelegramCore (definition + internal construction)
**`submodules/TelegramCore/Sources/TelegramEngine/Messages/SendAsPeers.swift`**
- Lines 7–21: struct definition. Change `peer: Peer` → `peer: EnginePeer`. Remove manual `==`; rely on synthesized Equatable.
- Line 64 (`_internal_cachedPeerSendAsAvailablePeers`): `SendAsPeer(peer: peer, …)` — wrap raw Postbox `Peer` with `EnginePeer(peer)`.
- Line 170 (`_internal_peerSendAsAvailablePeers`): same wrap.
- Line 236 (`_internal_cachedLiveStorySendAsAvailablePeers`): same wrap.
- Line 330 (`_internal_liveStorySendAsAvailablePeers`): same wrap.
- Lines 87, 90, 259, 262: `peer.peer.id` accesses inside the caching loop — `EnginePeer.id` returns `EnginePeer.Id` which is a typealias for `PeerId`; code keeps compiling.
No other TelegramCore files reference `SendAsPeer`.
### Category β — Pure token/init/access (no body edits expected)
**`submodules/ChatPresentationInterfaceState/Sources/ChatPresentationInterfaceState.swift`**
- Line 553: `public let sendAsPeers: [SendAsPeer]?` — field typed at collection level, no `.peer` access in this file.
- Lines 751–752 / 848 / 1068 / 1408: init parameter, assignment, equality comparison at `[SendAsPeer]?` level, and `updatedSendAsPeers(_:)` method. None reference the inner `.peer` field.
- Expected edits: zero. This file should remain untouched if the field-type migration is clean.
**`submodules/ChatPresentationInterfaceState/Sources/ChatPanelInterfaceInteraction.swift`**
- Out of scope: its `openSendAsPeer: (ASDisplayNode, ContextGesture?) -> Void` callback does NOT take a `SendAsPeer`; name-collision only.
### Category γ — Cast-downstream
**`submodules/TelegramUI/Components/Chat/ChatSendAsContextMenu/Sources/ChatSendAsPeerListContextItem.swift`**
- Lines 20, 26: `peers: [SendAsPeer]` field and constructor — no edit needed.
- Lines 68–82: iteration body.
- Line 70: `peer.peer.id.namespace == Namespaces.Peer.CloudUser` — unchanged (EnginePeer.Id retains `.namespace`).
- Line 73: **`if let peer = peer.peer as? TelegramChannel`** → rewrite as `if case let .channel(channelData) = peer.peer`, matching on the `EnginePeer` enum case. Downstream `channelData.info` access behaves the same; `case .broadcast = channelData.info` continues to compile because `EnginePeer.channel` wraps the same `TelegramChannel.Info` enum.
- Lines 89 / 110 / 116 / 121: `EnginePeer(peer.peer)` — drop the wrap, use `peer.peer` directly.
### Category δ — Outflow (construction and field access)
**`submodules/TelegramUI/Sources/Chat/ChatControllerLoadDisplayNode.swift`**
- Line 772: `SendAsPeer(peer: peer._asPeer(), …)` — drop `._asPeer()`; construction now takes `EnginePeer` directly. `peer` at this site is already an `EnginePeer` upstream.
- Lines 805, 823: `SendAsPeer(peer: channel, …)` where `channel` is a raw `TelegramChannel` — wrap with `EnginePeer(channel)`.
- Lines 792 / 826 / 835 / 844: `allPeers` array ops and `.peer.id` filter/find — unchanged.
**`submodules/TelegramUI/Components/Chat/ChatTextInputPanelNode/Sources/ChatTextInputPanelComponent.swift`**
- Line 847: `SendAsPeer(peer: sendAsConfiguration.currentPeer._asPeer(), …)` — drop `._asPeer()`. `sendAsConfiguration.currentPeer` is `EnginePeer` upstream.
- Line 851: `updatedSendAsPeers([…])` — unchanged.
**`submodules/TelegramUI/Components/Chat/ChatTextInputPanelNode/Sources/ChatTextInputPanelNode.swift`**
- Line 1625: `EnginePeer(peer)` where `peer` is now `EnginePeer` → collapses to `peer`.
- Lines 1616 / 1620 / 1622 / 2948 / 5370: `.peer.id` comparisons, `sendAsPeers.first(where:)` — unchanged.
**`submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerViewSendMessage.swift`**
- Line 249: `SendAsPeer(peer: accountPeer._asPeer(), …)` — drop `._asPeer()`.
- Line 4080: `(sendAsPeer?.peer).flatMap(EnginePeer.init)` → simplifies to `sendAsPeer?.peer` (already `EnginePeer?`).
- Line 4081: `.map({ EnginePeer($0.peer) })` → `.map({ $0.peer })`.
- Line 254 / 688 / 701 / 702 / 705 / 4050 / 4068 / 4069 / 4088 / 4089 / 4327 / 4333 / 4340 / 4356 / 4372: `.peer.id` accesses, variable bindings, optional access — unchanged.
- Line 4340: `call.sendStars(fromId: sendAsPeer?.peer.id, …)` — `EnginePeer.Id == PeerId`, unchanged.
**`submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerComponent.swift`**
- Lines 3056–3072: `sendMessageContext.currentSendAsPeer` pass-through to context-menu item. Verify call-site type expectations during implementation; likely no edit needed since `ChatSendAsPeerListContextItem` keeps taking `[SendAsPeer]`.
## Out-of-scope — name collisions (do not touch)
- `submodules/TelegramUI/Components/ShareWithPeersScreen/Sources/LiveStreamSettingsScreen.swift:271-272` — `screenState.sendAsPeers` is `[EnginePeer]` (see `ShareWithPeersScreen.swift:1114`). Different type, same name.
- `submodules/TelegramUI/Components/Chat/ChatSendStarsScreen/Sources/ChatSendStarsScreen.swift:1515,2749,2958` — `availableSendAsPeers: [EnginePeer]` enum-case payload. Different type, same name.
- `submodules/TelegramUI/Components/MediaEditorScreen/Sources/MediaEditorScreen.swift:7070`, `ShareWithPeersScreen.swift:39,57,74,817,1301,2352,3284,3453` — `initialSendAsPeerId: EnginePeer.Id?` / method names containing "SendAsPeer". PeerId parameter, not the struct.
- Callback declarations in `ChatPanelInterfaceInteraction.swift`, `AttachmentPanel.swift`, `PeerSelectionControllerNode.swift`, `ChatRecentActionsController.swift`, `PeerInfoSelectionPanelNode.swift` named `updateShowSendAsPeers` / `openSendAsPeer` — these take `(Bool)`/`(ASDisplayNode, ContextGesture?)`, not `SendAsPeer` values.
## Execution plan outline (for writing-plans)
Single atomic commit ordering:
1. Edit `SendAsPeers.swift` — change field type, init parameter, drop manual `==`, wrap raw `Peer` at the 4 construction sites with `EnginePeer(peer)`.
2. Edit `ChatSendAsPeerListContextItem.swift` — rewrite line 73 cast to EnginePeer case match; drop `EnginePeer(peer.peer)` wraps at 89/110/116/121.
3. Edit `ChatControllerLoadDisplayNode.swift` — drop `._asPeer()` at 772; wrap `channel` with `EnginePeer(channel)` at 805/823.
4. Edit `ChatTextInputPanelComponent.swift` — drop `._asPeer()` at 847.
5. Edit `ChatTextInputPanelNode.swift` — collapse `EnginePeer(peer)` at 1625 to `peer`.
6. Edit `StoryItemSetContainerViewSendMessage.swift` — drop `._asPeer()` at 249; simplify flatMap at 4080; simplify map at 4081.
7. Verify `ChatPresentationInterfaceState.swift` and `StoryItemSetContainerComponent.swift` need no body edits.
8. Build: `source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion --cacheDir ~/telegram-bazel-cache build --configurationPath build-system/appstore-configuration.json --gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git --gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 --configuration=debug_sim_arm64 --continueOnError`.
9. Fix any files the inventory undercounted (expect scalar `.peer` accesses in closure bodies). Commit once build is green.
## Risk register
| Risk | Mitigation |
|------|------------|
| Inventory undercount (wave 34 lost ~30%) | Pre-flight grep already includes `.peer as?`/`is`/outflow; use `--continueOnError` on first build to surface all sites in one pass. |
| Cast at `ChatSendAsPeerListContextItem:73` doesn't round-trip | `EnginePeer.channel(TelegramChannel)` wraps the exact same concrete type; the `if case let .channel(ch)` rewrite preserves all `ch.info`/`ch.flags`/etc. semantics. |
| `SendAsPeer` Equatable synthesis regression | `EnginePeer` and `Int32?` and `Bool` are all Equatable; synthesized `==` produces the same truth table modulo replacing `Peer.isEqual` with `EnginePeer ==` (which for `.channel(a)` vs `.channel(b)` compares the underlying `TelegramChannel` via its own Equatable). No behavior change expected. |
| `StoryItemSetContainerComponent.swift:3056-3072` outflow missed | Plan step 7 verifies this during implementation; if a wrap/unwrap is needed at the context-menu boundary, add it inline. |
## Validation
- Full Bazel build (`--configuration=debug_sim_arm64 --continueOnError`).
- No TelegramCore/Postbox/TelegramApi errors (scope boundary check — halt if they surface).
- Grep post-commit: `rg "SendAsPeer\(peer: .*\._asPeer" submodules/` returns empty.
- Grep post-commit: `rg "EnginePeer\(.*\.peer\b" submodules/TelegramUI/Components/Chat/ChatSendAsContextMenu` returns empty.
## Lessons to carry forward
- Wave 34's grep pattern (`<Type>`-literal token only) undercounted ~30%. This wave's Explore inventory explicitly included `.peer as?`/`is`/outflow-helper/`EnginePeer(.peer)` / `._asPeer()` patterns. Record the post-commit file count vs. pre-commit inventory to calibrate future Peer-typed-API waves.
- Name collisions (different types, same identifier) are a recurring scoping hazard — confirmed in this wave for `sendAsPeers: [EnginePeer]` and `availableSendAsPeers: [EnginePeer]`. Future Peer-typed-API waves should include a name-collision disambiguation pass during inventory.

127
docs/superpowers/specs/2026-04-25-peerinfo-enclosingpeer-engine-peer.md
View file

@ -1,127 +0,0 @@
# Wave 50 — `enclosingPeer` Peer? → EnginePeer?
**Date:** 2026-04-25
**Pattern:** struct-field + stored-form `Peer?` → `EnginePeer?` (wave-47/48 shape).
**Module:** `submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/` only — no public-API leaks.
## Goal
Migrate the PeerInfo members chain's `enclosingPeer` field from raw Postbox `Peer?` to `EnginePeer?`. Drops 2 `_asPeer()` demotions, 1 `EnginePeer(...)` wrap, 1 `flatMap(EnginePeer.init)` simplification, and 1 PSPB boundary `_asPeer()` lift. Closes the wave-48-pattern internal-demotion-and-external-re-promotion ratchet at PIMP:354–363 (engine.data subscription returns `EnginePeer?`, currently demoted to `Peer?` at the storage boundary).
## Type changes
| File | Site | Before | After |
|---|---|---|---|
| `PeerInfoScreenMemberItem.swift:23` | stored `let enclosingPeer` | `Peer?` | `EnginePeer?` |
| `PeerInfoScreenMemberItem.swift:34` | init param | `Peer?` | `EnginePeer?` |
| `PeerInfoMembersPane.swift:92` | `func item(... enclosingPeer:)` | `Peer` | `EnginePeer` |
| `PeerInfoMembersPane.swift:271` | `func preparedTransition(... enclosingPeer:)` | `Peer` | `EnginePeer` |
| `PeerInfoMembersPane.swift:293` | `private var enclosingPeer` | `Peer?` | `EnginePeer?` |
| `PeerInfoMembersPane.swift:442` | `func updateState(enclosingPeer:)` | `Peer` | `EnginePeer` |
`PeerInfoScreenMemberItem` and `PeerInfoMembersPaneNode` are local to the module — no cross-module signature ripple.
## Edit patterns
### A. Conditional cast → case-let (wave-41/45 idiom)
| File:Line | Before | After |
|---|---|---|
| PSMI:152 | `if let channel = item.enclosingPeer as? TelegramChannel, channel.hasPermission(.editRank)` | `if case let .channel(channel) = item.enclosingPeer, channel.hasPermission(.editRank)` |
| PSMI:154 | `else if let group = item.enclosingPeer as? TelegramGroup, !group.hasBannedPermission(.banEditRank)` | `else if case let .legacyGroup(group) = item.enclosingPeer, !group.hasBannedPermission(.banEditRank)` |
| PIMP:113 | `if let channel = enclosingPeer as? TelegramChannel, channel.hasPermission(.editRank)` | `if case let .channel(channel) = enclosingPeer, channel.hasPermission(.editRank)` |
| PIMP:115 | `else if let group = enclosingPeer as? TelegramGroup, !group.hasBannedPermission(.banEditRank)` | `else if case let .legacyGroup(group) = enclosingPeer, !group.hasBannedPermission(.banEditRank)` |
The `case let` pattern binds `channel: TelegramChannel` / `group: TelegramGroup` directly — `.hasPermission(.editRank)` and `.hasBannedPermission(.banEditRank)` are class methods on the bound concrete types. No `_asPeer()` bridge needed.
### B. `is`-check → `case` (wave-41 always-false-warning fix)
| File:Line | Before | After |
|---|---|---|
| PSMI:181 | `if actions.contains(.promote) && item.enclosingPeer is TelegramChannel` | `if actions.contains(.promote), case .channel = item.enclosingPeer` |
| PSMI:187 | `if item.enclosingPeer is TelegramChannel` | `if case .channel = item.enclosingPeer` |
| PIMP:142 | `if actions.contains(.promote) && enclosingPeer is TelegramChannel` | `if actions.contains(.promote), case .channel = enclosingPeer` |
| PIMP:148 | `if enclosingPeer is TelegramChannel` | `if case .channel = enclosingPeer` |
PIMP:113/115/142/148 are inside `func item(... enclosingPeer: EnginePeer ...)`, so `enclosingPeer` is non-optional inside that body; PSMI sites are against `item.enclosingPeer: EnginePeer?`. `case let .channel(channel)` and `case .channel` both compile cleanly against optional and non-optional EnginePeer.
### C. Drop wraps / unwraps
| File:Line | Before | After |
|---|---|---|
| PSMI:178 | `peer: item.enclosingPeer.flatMap(EnginePeer.init)` | `peer: item.enclosingPeer` |
| PIMP:139 | `peer: EnginePeer(enclosingPeer)` | `peer: enclosingPeer` |
| PIMP:361 | `strongSelf.enclosingPeer = enclosingPeer._asPeer()` | `strongSelf.enclosingPeer = enclosingPeer` |
| PIMP:363 | `updateState(enclosingPeer: enclosingPeer._asPeer(), state: state, presentationData: presentationData)` | `updateState(enclosingPeer: enclosingPeer, state: state, presentationData: presentationData)` |
| PSPB:852 | `enclosingPeer: peer._asPeer()` | `enclosingPeer: peer` |
### D. No-op call sites (type flows through transparently)
- `PeerInfoSettingsItems.swift:132` — `enclosingPeer: nil` (nil literal works for any optional)
- `PeerInfoMembersPane.swift:275/276` — pass-through `enclosingPeer: enclosingPeer`
- `PeerInfoMembersPane.swift:437/438` — `if let enclosingPeer = self.enclosingPeer ... self.updateState(enclosingPeer: enclosingPeer, ...)` (both stored-form and `updateState` param shift to EnginePeer; type carries through)
- `PeerInfoMembersPane.swift:451` — pass-through
- `PeerInfoMembersPane.swift:485` — `self.enclosingPeer = enclosingPeer` (param and stored-form both EnginePeer)
- `PeerInfoScreenOpenMember.swift` — uses `self.data?.peer` (already `EnginePeer?` post-wave-42), unrelated to this migration
**Total edits:** 19 across 3 files (PSMI, PIMP, PSPB) — 6 type-change edits in the table at the top of this spec + 4 (Pattern A) + 4 (Pattern B) + 5 (Pattern C).
## Risk register
| Risk | Mitigation |
|---|---|
| `case .channel = item.enclosingPeer` against `EnginePeer?` semantics | Wave-45 lesson confirms `case let .x(y) = peer` compiles cleanly against `EnginePeer?`. Matches `.some(.channel)`, rejects `nil` and other cases — equivalent to `is TelegramChannel` semantics. |
| `if actions.contains(.promote), case .channel = ...` mixed boolean + pattern condition | Standard Swift if-case syntax (introduced in wave 41 idiom for this codebase). |
| Hidden Peer-only property access on bare `enclosingPeer` | Pre-flight grep complete: only access patterns are `.id` (EnginePeer has it), and cast-bound `channel.hasPermission` / `group.hasBannedPermission`. No `_asPeer()` bridges expected. |
| Closure capture aliases (wave-47 lesson) | Pre-flight grep covered `strongSelf.enclosingPeer` (PIMP:361) and `self.enclosingPeer` (PIMP:437/485). |
| `enclosingPeer: nil` literal at PSI:132 | `nil` is valid for any optional — no edit. |
| `availableActionsForMemberOfPeer` signature compatibility | Confirmed `EnginePeer?` at `PeerInfoData.swift:2314`. Both PSMI:178 and PIMP:139 are pure simplifications. |
| Always-false `is` check warning under `-warnings-as-errors` | Wave-41 lesson — handled by Pattern B. |
## Wave shape
**Classification:** cross-file private struct-field migration with stored-form ratchet (wave-47 taxonomy: "cross-file private").
**Iteration budget:** 1–2 (target first-pass-clean per wave 48/49 streak).
**Subagent dispatch:** not needed — 17 edits / 3 files is single-implementer scope.
## Verification
### Build
```sh
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent \
--buildNumber=1 --configuration=debug_sim_arm64 --continueOnError
```
### Post-edit residue grep (expect empty)
```sh
grep -rnE "enclosingPeer\._asPeer|EnginePeer\(enclosingPeer\)|enclosingPeer\.flatMap\(EnginePeer" \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/
grep -rnE "enclosingPeer.*as\? TelegramChannel|enclosingPeer.*as\? TelegramGroup|enclosingPeer is TelegramChannel" \
submodules/TelegramUI/Components/PeerInfo/PeerInfoScreen/Sources/
```
## Net delta projection
- **Internal bridges:** −5 (2× `_asPeer()` at PIMP:361/363, 1× `EnginePeer(...)` at PIMP:139, 1× `flatMap(EnginePeer.init)` at PSMI:178, 1× boundary `_asPeer()` at PSPB:852).
- **Boundary lifts:** 0 net new — the source pipeline (engine.data subscription at PIMP:354) already yields `EnginePeer?`. Migration just removes the demote-then-promote dance.
- **ADD wraps:** 0 expected (no Peer-only property accesses on bare `enclosingPeer`).
## Out of scope
- `PeerInfoScreenData.chatPeer: Peer?` — large cascade (PSPB `as? TelegramX` × 5, ClearPeerHistory cascade, openClearHistory wraps × 4, PSOC × 2). Memory's wave-50 candidate Option 3, deferred for a multi-iteration wave.
- `PeerInfoGroupsInCommonPaneNode.PeerEntry.peer: Peer` — separate single-file migration, not bundled (wave-49 source-of-truth-coherence rule: unrelated chains stay in their own waves). Candidate for wave 51.
- `RenderedPeer → EngineRenderedPeer` foundational refactor — dedicated session.
## Memory file update
After landing, update `project_postbox_refactor_next_wave.md`:
- Move wave 50 outcome into the recent-waves list.
- Promote wave 51 candidate (`PeerInfoGroupsInCommonPaneNode.PeerEntry.peer` likely; otherwise re-scan the module with the standard grep).

120
docs/superpowers/specs/2026-04-26-postbox-wave-103-chat-recent-actions-controller-node-design.md
View file

@ -1,120 +0,0 @@
# Wave 103 — `ChatRecentActionsControllerNode.peer: Peer → EnginePeer`
**Date:** 2026-04-26
**Pattern:** close-the-shadow boundary unwrap drop (wave-71-shadow). Single-file private stored-field migration with caller-side `_asPeer()` removal at the module boundary.
**Module:** `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/` only — no public-API leak.
## Goal
Migrate `ChatRecentActionsControllerNode`'s stored `peer: Peer` to `EnginePeer`, dropping the `_asPeer()` boundary call inside `ChatRecentActionsController`. Net effect: −1 `_asPeer()` boundary wrap, −1 `import Postbox`, −1 module from the Postbox-importing list.
The caller (`ChatRecentActionsController`) already holds `peer: EnginePeer` and demotes it once at line 277 before passing into the ControllerNode init. This is the wave-71-shadow shape: the public API is already `EnginePeer`, but a private internal storage form was left as `Peer` at wave-71 time. Closing it now is a clean, contained migration.
## Type changes
| File | Site | Before | After |
|---|---|---|---|
| `ChatRecentActionsControllerNode.swift:46` | stored `private let peer` | `Peer` | `EnginePeer` |
| `ChatRecentActionsControllerNode.swift:111` | init param `peer:` | `Peer` | `EnginePeer` |
| `ChatRecentActionsControllerNode.swift:5` | `import Postbox` | present | removed |
| `ChatRecentActionsController.swift:277` | call `peer: self.peer._asPeer()` | demoted | `peer: self.peer` |
`ChatRecentActionsControllerNode` has no public-API consumers outside `ChatRecentActionsController` (single caller site verified by grep `ChatRecentActionsControllerNode\(`).
## Edit patterns
### A. Conditional cast → case-let (wave-41/45 idiom)
| File:Line | Before | After |
|---|---|---|
| ChatRecentActionsControllerNode.swift:899 | `if let peer = strongSelf.peer as? TelegramChannel { ... }` | `if case let .channel(peer) = strongSelf.peer { ... }` |
| ChatRecentActionsControllerNode.swift:948 | `if let channel = self.peer as? TelegramChannel, case .broadcast = channel.info { ... }` | `if case let .channel(channel) = self.peer, case .broadcast = channel.info { ... }` |
| ChatRecentActionsControllerNode.swift:1088 | `if let channel = self.peer as? TelegramChannel { ... }` | `if case let .channel(channel) = self.peer { ... }` |
The `case let .channel(channel)` pattern binds `channel: TelegramChannel` directly. Inner code (`channel.info`, etc.) ports verbatim because `EnginePeer.channel`'s associated value is the concrete `TelegramChannel` class.
`self.peer` is non-optional `EnginePeer` post-migration, so all three case-let conditions compile cleanly without optional-chaining.
### B. Pass-through (no edit, type flows transparently)
- `self.peer.id` — 4 sites (lines 145, 161, 1138, 1490). `EnginePeer.id` is an `EnginePeer.Id` typealias of `PeerId`, identical at the call sites that consume it (`channelAdminEventLog(peerId:)`, `admins(peerId:)`, `updateChannelMemberBannedRights(peerId:)`, et al. all accept the typealiased form).
### C. Caller boundary drop
| File:Line | Before | After |
|---|---|---|
| ChatRecentActionsController.swift:277 | `ChatRecentActionsControllerNode(... peer: self.peer._asPeer(), ...)` | `ChatRecentActionsControllerNode(... peer: self.peer, ...)` |
`ChatRecentActionsController.peer` is already declared `EnginePeer` (init signature at line 42 confirmed).
**Total edits:** 7 across 2 files. 4 type-change edits (3 in node + 1 caller) + 3 case-let rewrites.
## Risk register
| Risk | Mitigation |
|---|---|
| Other unrelated `_asPeer()` and `EnginePeer(peer)` sites in the same file (lines 357, 368, 1005 / 263, 1009, 1011, 1208, 1222) | Pre-flight grep verified these all operate on DIFFERENT `peer` locals (callback-bound search results, not `self.peer`). They are unaffected by this migration. |
| Hidden `Peer`-only property access on `self.peer` | Pre-flight grep complete: only attribute access is `.id` (EnginePeer-compatible). 3 `as? TelegramChannel` downcasts are the only conversion sites, all handled by Pattern A. |
| `as? TelegramGroup` or `as? TelegramUser` downcasts on `self.peer` | None present (verified by grep `self\.peer as\?` returning only the 3 TelegramChannel sites). |
| `is TelegramChannel`-style always-false warning under `-warnings-as-errors` | None present (no `is`-checks on `self.peer` — verified by grep). |
| Closure capture alias migration (wave-47 lesson) | Only `strongSelf.peer` and `self.peer` aliases — both ride the type change. No locally-bound `let peer = self.peer` aliases that would need separate type-flow tracking (verified by grep). |
| Caller side-effects from `_asPeer()` removal | `ChatRecentActionsController.swift:277` is the only call site (verified). The `_asPeer()` is pure conversion with no side effects. |
| Build cascade beyond the two files | Consumer-only — both files are inside `submodules/TelegramUI/Components/Chat/ChatRecentActionsController/`. No TelegramCore touch, no cross-module ripple. Build cost ~25s. |
## Wave shape
**Classification:** wave-71-shadow close (single-file private stored-form migration with single-caller boundary drop).
**Iteration budget:** 1 (target first-pass-clean given the contained scope and validated pre-flight grep).
**Subagent dispatch:** not needed — 7 edits across 2 files is single-implementer scope.
## Verification
### Build
```sh
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent \
--buildNumber=1 --configuration=debug_sim_arm64
```
(No `--continueOnError` — single-iter target with small scope.)
### Post-edit residue grep (expect empty)
```sh
# No remaining as? TelegramChannel on self.peer / strongSelf.peer
grep -nE "(self|strongSelf)\.peer as\? Telegram(Channel|Group|User)" \
submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/
# No remaining _asPeer() on self.peer
grep -nE "self\.peer\._asPeer\(\)" \
submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/
# No remaining import Postbox in the module
grep -rn "^import Postbox$" \
submodules/TelegramUI/Components/Chat/ChatRecentActionsController/Sources/
```
## Net delta projection
- **Internal bridges:** −1 (the `_asPeer()` at `ChatRecentActionsController.swift:277`).
- **`import Postbox` drops:** −1 (`ChatRecentActionsControllerNode.swift:5`).
- **ADD wraps:** 0 (no Peer-only property accesses on bare `self.peer`).
- **Module Postbox-free count:** +1.
## Out of scope
- Other `Peer`-typed locals in the same file (search-callback-bound `peer` at lines 357, 368, 1005, etc.) — these belong to separate signatures (`Signal<Peer?, NoError>`, search result destructures from APIs that still return raw `Peer`). Migrating them is gated on those upstream APIs migrating first.
- `context.account.postbox.network` and similar Shape-D Postbox accesses — unrelated to this wave's `peer` field migration.
- `EnginePeer(peer)` boundary wraps inside callbacks (lines 263, 1009, 1011, 1208, 1222) — these wrap callback-bound search results, not `self.peer`. Out of scope for the same reason as above.
## Memory file update
After landing, update `project_postbox_refactor_next_wave.md`:
- Move wave 103 outcome into the recent-waves list (commit hash + 7-edit single-iter summary).
- Update the "Wave 103+ Shape-C/D candidates" line in `MEMORY.md` since this is technically a wave-71-shadow close, not a Shape-C/D refactor — the candidates listed there (NativeVideoContent, DirectMediaImageCache, SecureIdDocumentFormControllerNode) carry forward to wave 104+.
- The `ChatRecentActionsControllerNode.peer: Peer -> EnginePeer` candidate line in the next-wave file (currently bullet 5) gets removed.

149
docs/superpowers/specs/2026-04-26-postbox-wave-103-retry-account-manager-store-resource-data-drain.md
View file

@ -1,149 +0,0 @@
# Wave 103 (retry) — accountManager.mediaBox.storeResourceData drain
**Date:** 2026-04-26
**Pattern:** wave-shape-G drain of an existing TelegramCore facade (the wave-94 `AccountManagerResources.storeResourceData(id:data:synchronous:)`).
**Module:** `submodules/TelegramUI/Sources/ThemeUpdateManager.swift` + `submodules/WallpaperResources/Sources/WallpaperResources.swift` only — no TelegramCore touch, no public-API change.
## Goal
Drain the 5 remaining `accountManager.mediaBox.storeResourceData(...)` Shape-A sites that the wave-94/95-99 sweep didn't catch. Migrate each to `accountManager.resources.storeResourceData(id: EngineMediaResource.Id(...), data: ..., synchronous: ...)` against the existing wave-94 facade. Net effect: −5 raw `accountManager.mediaBox.X` accesses, +5 facade calls. Consumer-only build.
This is the wave-103 retry after the abandonment of `ChatRecentActionsControllerNode.peer` migration (see `postbox-refactor-log.md` "Wave 103 outcome (2026-04-26): ABANDONED").
## Wave-71-shadow risk inventory (per `feedback_wave71_shadow_risk.md`)
| Layer | Applicable? | Notes |
|---|---|---|
| 1. Downcasts (`as?` / `is`) | N/A | No Peer migration, no type-level change |
| 2. Peer-protocol extension method calls | N/A | No stored field retype |
| 3. Field flow into Peer-typed function parameters | N/A | No `peer` param involved |
| 4. Message-builder cascade via `SimpleDictionary<PeerId, Peer>` | N/A | No `Message(...)` construction touched |
Wave shape (call-site rewrite against an existing facade) is orthogonal to the wave-71-shadow risk layers. The wave-94 lesson and wave-shape-G recipe are the relevant precedents.
## Sites (5 total)
### ThemeUpdateManager.swift (1 site)
| Line | Existing | Migrated |
|---|---|---|
| 112 | `accountManager.mediaBox.storeResourceData(file.file.resource.id, data: fullSizeData, synchronous: true)` | `accountManager.resources.storeResourceData(id: EngineMediaResource.Id(file.file.resource.id), data: fullSizeData, synchronous: true)` |
`accountManager` flows from the enclosing `presentationThemeSettingsUpdated(_:)` method's closure-captured scope. `accountManager: AccountManager<TelegramAccountManagerTypes>` typed (Shape-A).
### WallpaperResources.swift (4 sites)
All four sites use the same call-text pattern (same arity, no `synchronous:` arg) but different argument expressions:
| Line | Argument expression |
|---|---|
| 973 | `reference.resource.id, data: data` |
| 1214 | `reference.resource.id, data: data` |
| 1260 | `file.file.resource.id, data: fullSizeData` |
| 1523 | `file.file.resource.id, data: fullSizeData` |
Lines 973 and 1214 share identical text (`accountManager.mediaBox.storeResourceData(reference.resource.id, data: data)`) — `Edit replace_all=true` bundles them. Lines 1260 and 1523 share identical text (`accountManager.mediaBox.storeResourceData(file.file.resource.id, data: fullSizeData)`) — same.
Each migrated to: `accountManager.resources.storeResourceData(id: EngineMediaResource.Id(<argument expression>), data: <data expression>)`.
`accountManager` flows from `wallpaperDatas(account:accountManager:...)` and other public functions in the file, all parameter-typed `AccountManager<TelegramAccountManagerTypes>` (Shape-A).
## Edit patterns
### A. ThemeUpdateManager (1 site)
Single Edit:
| File:Line | Before | After |
|---|---|---|
| ThemeUpdateManager.swift:112 | `accountManager.mediaBox.storeResourceData(file.file.resource.id, data: fullSizeData, synchronous: true)` | `accountManager.resources.storeResourceData(id: EngineMediaResource.Id(file.file.resource.id), data: fullSizeData, synchronous: true)` |
### B. WallpaperResources (4 sites in 2 replace_all batches)
Two `Edit` calls, each with `replace_all=true`:
| Pattern | Before | After |
|---|---|---|
| Pattern 1 (lines 973, 1214) | `accountManager.mediaBox.storeResourceData(reference.resource.id, data: data)` | `accountManager.resources.storeResourceData(id: EngineMediaResource.Id(reference.resource.id), data: data)` |
| Pattern 2 (lines 1260, 1523) | `accountManager.mediaBox.storeResourceData(file.file.resource.id, data: fullSizeData)` | `accountManager.resources.storeResourceData(id: EngineMediaResource.Id(file.file.resource.id), data: fullSizeData)` |
**Total edits:** 3 Edit calls (1 single + 2 replace_all batches), 5 sites migrated.
## Facade signature reference
From `submodules/TelegramCore/Sources/AccountManager/AccountManagerResources.swift` (added wave 94):
```swift
public func storeResourceData(id: EngineMediaResource.Id, data: Data, synchronous: Bool = false) {
self.mediaBox.storeResourceData(MediaResourceId(id.stringRepresentation), data: data, synchronous: synchronous)
}
```
`EngineMediaResource.Id(_ id: MediaResourceId)` constructor at `TelegramCore/Sources/TelegramEngine/Resources/TelegramEngineResources.swift:179`.
`accountManager.resources` is a computed property that constructs a fresh `AccountManagerResources` wrapper holding only a `MediaBox` reference — cheap.
## Risk register
| Risk | Mitigation |
|---|---|
| `replace_all=true` matching the wrong site | Two patterns are scoped narrowly enough (full call expressions including the closing paren). Pre-flight grep confirmed exactly 2 instances of each pattern across the file. |
| `EngineMediaResource.Id(...)` constructor missing for the argument expression's type | Verified: `init(_ id: MediaResourceId)` exists. `MediaResource.id` returns `MediaResourceId` per Postbox protocol. Construction is canonical. |
| `synchronous:` default mismatch | Facade default is `synchronous: false`, matching `MediaBox.storeResourceData`'s underlying default. Sites without explicit `synchronous:` keep behavior. |
| Build cascade beyond touched files | Consumer-only — both files are leaf consumers (no public re-export of touched symbols). No TelegramCore touch. WallpaperResources is foundational so its rebuild fans out, but the public API is unchanged so dependent modules don't need recompilation. |
| WIP-interference at staging | Pre-existing WIP markers (`build-system/bazel-rules/sourcekit-bazel-bsp` + 3 untracked dirs) are in unrelated paths — no overlap. Stage by explicit file list. |
## Wave shape
**Classification:** wave-shape-G drain of an existing TelegramCore facade (waves 84-93 cohort, validated wave 94 + waves 95-99 drains).
**Iteration budget:** 1 (target first-pass-clean given mechanical scope and 5-site footprint).
**Subagent dispatch:** not needed — 3 Edit calls is single-implementer scope.
## Verification
### Build
```sh
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent \
--buildNumber=1 --configuration=debug_sim_arm64
```
(No `--continueOnError` — small atomic scope.) WallpaperResources is a foundational submodule with a wide rebuild fan-out, but its public API is unchanged so dependents don't recompile. Build cost projection: ~30-60s.
### Post-edit residue grep (expect empty)
```sh
grep -rn "accountManager\.mediaBox\.storeResourceData" \
submodules/TelegramUI/Sources/ThemeUpdateManager.swift \
submodules/WallpaperResources/Sources/WallpaperResources.swift
```
Expected: empty output across both files.
## Net delta projection
- **Raw `mediaBox.X` accesses:** −5
- **Facade `resources.X` calls:** +5
- **`EngineMediaResource.Id(...)` wraps:** +5 (these are canonical engine-side constructs, not Postbox bridges — they don't count as `_asPeer()`-style ADD wraps)
- **`import Postbox` drops:** 0 (both files retain `import Postbox` for unrelated symbols — this wave doesn't promise an import drop)
- **Postbox-free module count:** 0 net change
## Out of scope
- 7 `accountManager.mediaBox.resourceData(...)` sites — could use the existing `AccountManagerResources.data(resource:)` facade or a future `data(id:)` facade. Defer to a future drain wave.
- 22 `accountManager.mediaBox.cachedResourceRepresentation(...)` sites — Option A holdover, blocked by `CachedMediaResourceRepresentation` Postbox protocol leak. Needs facade-design pass.
- 3 `accountManager.mediaBox.storeCachedResourceRepresentation(...)` sites — same blocker.
- 2 `accountManager.mediaBox.cachedRepresentationCompletePath(...)` sites — same blocker.
- The `accountManager.mediaBox.cachedResourceRepresentation(...)` call at WallpaperResources:1261 and :1524 — directly adjacent to two of our migrated sites but blocked. Leave in place; the migrated `storeResourceData` call directly above it does not depend on it.
## Memory file update
After landing, update `project_postbox_refactor_next_wave.md`:
- Add wave 103 (retry) outcome line into the recent-waves section.
- Mark the 5 sites as drained; remove from candidate inventories.
- Promote the next candidate (likely the 7-site `resourceData` drain or one of the foundational waves).

148
docs/superpowers/specs/2026-04-26-postbox-wave-104-account-manager-resource-data-drain-3-sites.md
View file

@ -1,148 +0,0 @@
# Wave 104 — accountManager.mediaBox.resourceData drain (3 clean sites)
**Date:** 2026-04-26
**Pattern:** wave-shape-G drain of an existing TelegramCore facade (the wave-32 / wave-94 `AccountManagerResources.data(resource:pathExtension:waitUntilFetchStatus:attemptSynchronously:)`) with a documented field rename at consumer sites (`.complete` → `.isComplete`).
**Module:** `submodules/WallpaperResources/Sources/WallpaperResources.swift` only.
## Goal
Drain 3 of 8 `accountManager.mediaBox.resourceData(...)` Shape-A sites against the existing facade. Net effect: −3 raw `accountManager.mediaBox.X` accesses, +3 facade calls, +3 `EngineMediaResource(...)` wraps, +3 consumer `.complete` → `.isComplete` renames.
The remaining 5 sites are deferred: 2 (`FetchCachedRepresentations.swift:482, 490`) flow `data: MediaResourceData` into `fetchCachedScaledImageRepresentation` / `fetchCachedBlurredWallpaperRepresentation` — both expect raw Postbox `MediaResourceData`, so migration would force a cascade or boundary reconstruction. 3 (`WallpaperResources.swift:33, 59, 401`) are coupled to postbox-side via `combineLatest(accountManager.mediaBox.resourceData, account.postbox.mediaBox.resourceData)` returning typed `Signal<(MediaResourceData, MediaResourceData), NoError>` — migrating one side without the other breaks the tuple type.
## Wave-71-shadow risk inventory (per `feedback_wave71_shadow_risk.md`)
| Layer | Applicable? | Notes |
|---|---|---|
| 1. Downcasts | N/A | No type-level migration |
| 2. Peer-protocol extension method calls | N/A | Not a peer migration |
| 3. Field flow into Peer-typed function parameters | Adapted: result-type flow into MediaResourceData-typed params | **Cleared:** all 3 sites consume `maybeData.complete` and `maybeData.path` inline within the closure — no flow-out to functions taking raw `MediaResourceData`. Sites that DO flow out (482/490) are deferred. |
| 4. Message-builder cascade | N/A | No `Message(...)` construction touched |
The "data: MediaResourceData" parameter at `fetchCachedScaledImageRepresentation:311` / `fetchCachedBlurredWallpaperRepresentation:453, 502` is the analogue of the wave-103 `Message.peers` constructor barrier — a Postbox-typed function-parameter barrier that forces ADD bridges if upstream migrates. The 3 chosen sites do not cross this barrier; the deferred 2 sites do.
## Sites (3 total)
### Call rewrites
| Line | Existing call | Migrated call |
|---|---|---|
| 957 | `let maybeFetched = accountManager.mediaBox.resourceData(reference.resource, option: .complete(waitUntilFetchStatus: false), attemptSynchronously: synchronousLoad)` | `let maybeFetched = accountManager.resources.data(resource: EngineMediaResource(reference.resource), attemptSynchronously: synchronousLoad)` |
| 1164 | `let maybeFetched = accountManager.mediaBox.resourceData(fileReference.media.resource, option: .complete(waitUntilFetchStatus: false), attemptSynchronously: synchronousLoad)` | `let maybeFetched = accountManager.resources.data(resource: EngineMediaResource(fileReference.media.resource), attemptSynchronously: synchronousLoad)` |
| 1264 | `return accountManager.mediaBox.resourceData(file.file.resource)` | `return accountManager.resources.data(resource: EngineMediaResource(file.file.resource))` |
**`waitUntilFetchStatus: false` is omitted** in the migrated form — the facade signature has `waitUntilFetchStatus: Bool = false` as default. Sites 957/1164 explicitly pass `false`; site 1264 uses the underlying default.
### Consumer-side renames (`.complete` → `.isComplete`)
| Line | Existing | Migrated |
|---|---|---|
| 961 | ` if maybeData.complete {` | ` if maybeData.isComplete {` |
| 1168 | ` if maybeData.complete && isSupportedTheme {` | ` if maybeData.isComplete && isSupportedTheme {` |
| 1266 | ` if data.complete, let imageData = try? Data(contentsOf: URL(fileURLWithPath: data.path)) {` | ` if data.isComplete, let imageData = try? Data(contentsOf: URL(fileURLWithPath: data.path)) {` |
### Sites NOT migrated (deferred)
- L33, L59, L401 — `combineLatest(accountManager.mediaBox.resourceData(X), account.postbox.mediaBox.resourceData(X))` (typed tuple return)
- L482, L490 (in FetchCachedRepresentations.swift, not WallpaperResources.swift) — `data: MediaResourceData` flow-out cascade
- The closure bodies at sites 957, 1164 contain INNER `account.postbox.mediaBox.resourceData(...)` calls and inner `data.complete` accesses on a different binding (the postbox-side result) — those stay raw and are NOT touched by this wave. Only the OUTER `maybeFetched`-typed result is migrated.
## Type reference
Facade signature (existing, wave-32 / wave-94):
```swift
public func data(
resource: EngineMediaResource,
pathExtension: String? = nil,
waitUntilFetchStatus: Bool = false,
attemptSynchronously: Bool = false
) -> Signal<EngineMediaResource.ResourceData, NoError>
```
`EngineMediaResource.ResourceData` (final class at `TelegramCore/Sources/TelegramEngine/Resources/TelegramEngineResources.swift:149`):
- `public let path: String` (matches `MediaResourceData.path`)
- `public let availableSize: Int64`
- `public let isComplete: Bool` (renamed from `MediaResourceData.complete`)
`EngineMediaResource(_ resource: MediaResource)` constructor — canonical wrap (CLAUDE.md cheat sheet).
## Edit patterns
6 separate Edit calls in 1 file. No `replace_all=true` opportunity — each call/rename has unique surrounding text.
**Order (recommended):** call rewrites first (3 edits), then consumer renames (3 edits). This sequence keeps the file in a half-migrated but compilable state between batches if interrupted (call site uses new facade, consumer still on old field name → swift compile error caught quickly).
Alternative order: per-site bundled (call + rename pair, then next pair) — also fine.
## Risk register
| Risk | Mitigation |
|---|---|
| `EngineMediaResource(rawResource)` constructor missing | Verified: constructor exists per CLAUDE.md cheat sheet ("EngineMediaResource(rawResource) — wrap a raw MediaResource"). |
| `.path` field mismatch | Verified: both `MediaResourceData.path` and `EngineMediaResource.ResourceData.path` are `String`. No edit needed at any `data.path` usage site. |
| `.availableSize` not exposed by `MediaResourceData` | None of the 3 consumers use `.availableSize`. Only `.complete` (renamed) and `.path` (unchanged) are used. |
| Inner `data.complete` accesses on postbox-side bindings get renamed by accident | The 3 renames are on distinct bindings (`maybeData`, `maybeData`, `data`) within distinct outer scopes. The inner `data.complete` at L968 (postbox-side closure body inside site 957) is on a DIFFERENT `data` binding — its surrounding text differs (`return data.complete ? try? Data(...)` vs the migrated `if data.complete, let imageData = try? Data(...)`). Each Edit's `old_string` includes enough surrounding text to disambiguate. |
| `Signal.complete()` confused with field rename | The renames target `<binding>.complete` (property access). `Signal.complete()` is a method call, syntactically distinct (`return .complete()`). No regex collision. |
| `attemptSynchronously: synchronousLoad` arg flows | Facade exposes `attemptSynchronously: Bool = false`. Site 957/1164 pass `synchronousLoad` (a function param of the same name, Bool-typed) — flows through unchanged. |
| Build cascade beyond touched file | WallpaperResources is foundational with wide rebuild fan-out, but the public API is unchanged so dependents don't recompile. Build cost projection: ~30-60s. |
## Wave shape
**Classification:** wave-shape-G drain of an existing TelegramCore facade with a documented consumer field rename. Mid-difficulty between wave-103-retry (pure mechanical) and wave-71-shadow (cascade-prone).
**Iteration budget:** 1 (target first-pass-clean given small footprint and verified pre-flight inventory).
**Subagent dispatch:** not needed — 6 edits in 1 file is single-implementer scope.
## Verification
### Build
```sh
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent \
--buildNumber=1 --configuration=debug_sim_arm64
```
(No `--continueOnError` — small atomic scope.) Build cost projection: ~30-60s.
### Post-edit residue grep (expect specific output, NOT empty)
```sh
grep -rn "accountManager\.mediaBox\.resourceData" submodules/WallpaperResources/Sources/WallpaperResources.swift
```
Expected: 3 lines remaining (L33, L59, L401 — the deferred combineLatest sites). Sites 957, 1164, 1264 should NOT appear.
```sh
grep -nE "maybeData\.complete\b|^.*\bdata\.complete\b" submodules/WallpaperResources/Sources/WallpaperResources.swift
```
Expected: a small number of lines remaining at unrelated sites (the postbox-side inner closure at site-957's L968 still uses `data.complete` on a postbox-side binding — that stays). Lines 961, 1168, 1266 should NOT appear.
## Net delta projection
| Category | Count | Sites |
|---|---|---|
| Raw `mediaBox.resourceData` accesses dropped | −3 | WR:957, 1164, 1264 |
| Facade calls added | +3 | same sites, migrated form |
| `EngineMediaResource(...)` wraps added | +3 | canonical engine-side wraps, not Postbox bridges |
| Consumer `.complete` → `.isComplete` renames | +3 | WR:961, 1168, 1266 |
| `import Postbox` drops | 0 | WallpaperResources retains Postbox import for unrelated symbols |
| Postbox-free module count | 0 | unchanged |
## Out of scope
- Sites 482/490 in FetchCachedRepresentations.swift — `data: MediaResourceData` cascade through `fetchCachedScaled*Representation` family. Defer to a session that designs the appropriate facade or migrates the cascade as a co-wave.
- Sites 33/59/401 in WallpaperResources.swift — `combineLatest(accountManager.mediaBox.resourceData, account.postbox.mediaBox.resourceData)` typed-tuple coupling. Defer until postbox-side `account.postbox.mediaBox.resourceData` is also drainable (Shape-C territory) or a paired-resource facade is designed.
- The 22 `cachedResourceRepresentation` accountManager-side sites — blocked by `CachedMediaResourceRepresentation` Postbox protocol leak.
## Memory file update
After landing, update `project_postbox_refactor_next_wave.md`:
- Add wave 104 outcome line into the recent-waves section.
- Update accountManager-side facade drain status table: `resourceData` count drops from 8 → 5 (3 drained, 5 deferred).
- Note the `fetchCachedScaled*Representation` cascade barrier — adds it to the list of "Postbox-typed-function-parameter barriers" alongside `Message.peers: SimpleDictionary<PeerId, Peer>`.

183
docs/superpowers/specs/2026-04-26-postbox-wave-105-device-contact-info-subject-engine-peer.md
View file

@ -1,183 +0,0 @@
# Wave 105 — DeviceContactInfoSubject enum payload Peer? → EnginePeer?
**Date:** 2026-04-26
**Pattern:** Multi-module enum-payload migration with completion-callback signature change (wave-91 shape — `ItemListWebsiteItem.peer + RecentSessionsController.website case payload + openWebSession callback`).
**Modules:** `AccountContext` (enum + computed property), `PeerInfoUI` (`DeviceContactInfoController.swift` primary consumer), `TelegramUI` (4 construction sites across 4 files).
## Goal
Migrate `DeviceContactInfoSubject` enum's 3 case payloads from `Peer?` to `EnginePeer?`, plus 2 callback signatures (`.filter`'s `(Peer?, DeviceContactExtendedData) -> Void` and `.create`'s `(Peer?, DeviceContactStableId, DeviceContactExtendedData) -> Void`) and the public `peer: Peer?` computed property. Net effect: −10 wraps dropped, +2 wraps added (Chat-side construction barriers), +1 `as? TelegramUser` → `case let .user(...)` rewrite. **Net wrap delta: −8.**
## Wave-71-shadow risk inventory (per `feedback_wave71_shadow_risk.md`)
| Layer | Result | Notes |
|---|---|---|
| 1. Downcasts (`as?` / `is`) on the migrated value | **1 site** | `DeviceContactInfoController.swift:849` — `if let peer = peer as? TelegramUser` becomes `if case let .user(peer) = peer`. Inner body accesses `peer.firstName`, `peer.lastName`, `peer.phone` — all `TelegramUser` fields, work after rebinding via case-let. |
| 2. Peer-protocol extension method calls | **0 blockers** | Inventory pass found ALL consumer-side access on the migrated bindings is `.id` only. No `Peer`-protocol-only methods (no `canSetupAutoremoveTimeout`, `displayTitle`, `addressName`, etc. on the migrated bindings). |
| 3. Field flow into `Peer`-typed function parameters | **2 ADD bridges** | `ChatControllerOpenAttachmentMenu.swift:683` and `:1850` — both pass `peerAndContactData.0` directly to `.filter(peer:)` constructor. The upstream signal type is explicitly `(Peer?, DeviceContactExtendedData?)` (see L634, L1822). After migration, the construction must wrap: `peerAndContactData.0.flatMap(EnginePeer.init)`. **Accepted barrier — net-negative wave delta still wins.** |
| 4. `Message`-builder / `SimpleDictionary<PeerId, Peer>` barriers | **0** | No `Message(...)` constructor calls or dict-store patterns on the migrated bindings. |
The 2 ADD bridges in Layer 3 are the only wave cost; net delta after accounting for them is still −8.
## Type changes
### AccountContext.swift (lines 703-718)
| Line | Before | After |
|---|---|---|
| 704 | `case vcard(Peer?, DeviceContactStableId?, DeviceContactExtendedData)` | `case vcard(EnginePeer?, DeviceContactStableId?, DeviceContactExtendedData)` |
| 705 | `case filter(peer: Peer?, contactId: DeviceContactStableId?, contactData: DeviceContactExtendedData, completion: (Peer?, DeviceContactExtendedData) -> Void)` | `case filter(peer: EnginePeer?, contactId: DeviceContactStableId?, contactData: DeviceContactExtendedData, completion: (EnginePeer?, DeviceContactExtendedData) -> Void)` |
| 706 | `case create(peer: Peer?, contactData: DeviceContactExtendedData, isSharing: Bool, shareViaException: Bool, completion: (Peer?, DeviceContactStableId, DeviceContactExtendedData) -> Void)` | `case create(peer: EnginePeer?, contactData: DeviceContactExtendedData, isSharing: Bool, shareViaException: Bool, completion: (EnginePeer?, DeviceContactStableId, DeviceContactExtendedData) -> Void)` |
| 708 | `public var peer: Peer? {` | `public var peer: EnginePeer? {` |
The `contactData: DeviceContactExtendedData` computed property at L719 is unchanged.
## Edit patterns
### Pattern A — `_asPeer()` drops at construction sites (5 sites)
| File:Line | Before | After |
|---|---|---|
| DeviceContactInfoController.swift:1289 | `subject: .vcard(peer?._asPeer(), contactId, contactData)` | `subject: .vcard(peer, contactId, contactData)` |
| DeviceContactInfoController.swift:1443 | `subject: .create(peer: peer?._asPeer(), contactData: contactData, isSharing: false, shareViaException: false, completion: { peer, stableId, contactData in` | `subject: .create(peer: peer, contactData: contactData, isSharing: false, shareViaException: false, completion: { peer, stableId, contactData in` |
| DeviceContactInfoController.swift:1489 | `subject: .create(peer: peer?._asPeer(), contactData: contactData, isSharing: peer != nil, shareViaException: false, completion: { _, _, _ in` | `subject: .create(peer: peer, contactData: contactData, isSharing: peer != nil, shareViaException: false, completion: { _, _, _ in` |
| StoryItemSetContainerViewSendMessage.swift:2132 | `subject: .filter(peer: peerAndContactData.0?._asPeer(), contactId: nil, contactData: contactData, completion: { [weak self, weak view] peer, contactData in` | `subject: .filter(peer: peerAndContactData.0, contactId: nil, contactData: contactData, completion: { [weak self, weak view] peer, contactData in` |
| OpenChatMessage.swift:443 | `subject: .vcard(peer?._asPeer(), nil, contactData)` | `subject: .vcard(peer, nil, contactData)` |
Each source `peer` is already `EnginePeer?` (verified per-site: line 1289 in `addContactToExisting` callback already typed `(EnginePeer?, ...)` at L1409; line 1443 in `dataSignal` callback that returns `(EnginePeer?, ...)`; line 1489 in `addContactOptionsController(peer: EnginePeer?, ...)`; line 2132 in `(EnginePeer?, ...)` signal; line 443 in `peer: EnginePeer?` source).
### Pattern B — `_asPeer()` drops at completion-call sites (2 sites)
| File:Line | Before | After |
|---|---|---|
| DeviceContactInfoController.swift:1105 | `completion(peerAndContactData.0?._asPeer(), filteredData)` | `completion(peerAndContactData.0, filteredData)` |
| DeviceContactInfoController.swift:1224 | `completion(contactIdAndData.2?._asPeer(), contactIdAndData.0, contactIdAndData.1)` | `completion(contactIdAndData.2, contactIdAndData.0, contactIdAndData.1)` |
The completion's first parameter type changes from `Peer?` to `EnginePeer?` per the enum migration. Source values (`peerAndContactData.0` and `contactIdAndData.2`) are already `EnginePeer?` (typed signal pipelines), so dropping `_asPeer()` is a clean simplification.
### Pattern C — `.flatMap(EnginePeer.init)` simplifications (3 sites)
DeviceContactInfoController.swift:941-946 region:
| File:Line | Before | After |
|---|---|---|
| 941-942 | `case let .vcard(peer, id, data):\n contactData = .single((peer.flatMap(EnginePeer.init), id, data))` | `case let .vcard(peer, id, data):\n contactData = .single((peer, id, data))` |
| 943-944 | `case let .filter(peer, id, data, _):\n contactData = .single((peer.flatMap(EnginePeer.init), id, data))` | `case let .filter(peer, id, data, _):\n contactData = .single((peer, id, data))` |
| 945-946 | `case let .create(peer, data, share, shareViaExceptionValue, _):\n contactData = .single((peer.flatMap(EnginePeer.init), nil, data))` | `case let .create(peer, data, share, shareViaExceptionValue, _):\n contactData = .single((peer, nil, data))` |
After migration, the destructured `peer: EnginePeer?` is already the target type — the `.flatMap(EnginePeer.init)` round-trip becomes redundant.
### Pattern D — Downcast → case-let (1 site)
| File:Line | Before | After |
|---|---|---|
| DeviceContactInfoController.swift:849 | `if let peer = peer as? TelegramUser {` | `if case let .user(peer) = peer {` |
The outer `peer` is bound from `case let .create(peer, contactData, _, _, _) = subject` at L845, which becomes `EnginePeer?` post-migration. `case let .user(peer) = peer` rebinds the inner `peer` to `TelegramUser` (the `.user` case associated value). Inner body accesses `peer.firstName`, `peer.lastName`, `peer.phone` — all `TelegramUser` instance methods/properties, work transparently after rebinding.
### Pattern E — ADD wraps at Chat-side construction (2 sites)
| File:Line | Before | After |
|---|---|---|
| ChatControllerOpenAttachmentMenu.swift:683 | `subject: .filter(peer: peerAndContactData.0, contactId: nil, contactData: contactData, completion: { peer, contactData in` | `subject: .filter(peer: peerAndContactData.0.flatMap(EnginePeer.init), contactId: nil, contactData: contactData, completion: { peer, contactData in` |
| ChatControllerOpenAttachmentMenu.swift:1850 | `subject: .filter(peer: peerAndContactData.0, contactId: nil, contactData: contactData, completion: { peer, contactData in` | `subject: .filter(peer: peerAndContactData.0.flatMap(EnginePeer.init), contactId: nil, contactData: contactData, completion: { peer, contactData in` |
Both sites have identical text — `Edit replace_all=true` bundles them. The upstream signal type is explicitly `(Peer?, DeviceContactExtendedData?)` (verified at L634 and L1822). The `.flatMap(EnginePeer.init)` wraps the optional `Peer?` to optional `EnginePeer?`.
### Pattern F — Pass-through (no edit needed)
These flow transparently through the type change:
- DeviceContactInfoController.swift:897, 1041, 1047 — `subject.peer` access (returns `EnginePeer?` post-migration, consumers use `.id` or `if let peer = subject.peer`)
- DeviceContactInfoController.swift:1041 — `.create(peer: subject.peer, ...)` — both sides EnginePeer? after migration
- DeviceContactInfoController.swift:1149-1163, 1183-1189 — destructured `peer` from `.create` becomes `EnginePeer?`, body accesses `peer.id` and passes to `completion(peer, ...)` (now `EnginePeer?`-accepting)
- ContactsController.swift:312, 785; OpenAddContact.swift:32; ComposeController.swift:220; ShareExtensionContext.swift:532 — `peer: nil` or `.vcard(nil, ...)` constructions, `nil` works for both optional types
- All callback consumer bodies that use `peer?.id` (StoryItemSetContainerViewSendMessage:2141, ChatControllerOpenAttachmentMenu:689, :1856) — `EnginePeer?.id` is `EnginePeer.Id` typealiased to `PeerId`, identical at usage sites
**Total edits: 17 across 5 files.** AccountContext.swift (4) + DeviceContactInfoController.swift (9) + ChatControllerOpenAttachmentMenu.swift (1 with replace_all) + StoryItemSetContainerViewSendMessage.swift (1) + OpenChatMessage.swift (1) = ~16 Edit calls.
## Risk register
| Risk | Mitigation |
|---|---|
| `_asPeer()` source not actually `EnginePeer?` at one of the drop sites | Per-site source typing verified during inventory: 1289 (addContactToExisting callback typed `(EnginePeer?, ...)` at L1409), 1443 (dataSignal returns `(EnginePeer?, ...)`), 1489 (function param `peer: EnginePeer?` at L1481), 2132 (signal callback typed `(EnginePeer?, ...)`), 443 (local `peer: EnginePeer?`). All confirmed. |
| `subject.peer` consumers break | 3 access sites, all pattern `if let peer = subject.peer { ... peer.id ... }`. Body uses `.id` (transparent). |
| Closure capture aliases of destructured `peer` flow into untyped contexts | Inventory found 8 destructure sites; all body uses are `.id` access or pass-through to completion calls (whose signature also migrates). |
| Build cascade through AccountContext consumers | AccountContext is foundational. The enum + computed property changes cascade ALL consumers. Build cost projection: 60-180s. |
| `case let .user(peer)` rebinding shadow at L849 | The outer `peer` (EnginePeer?) is shadowed by the inner `peer` (TelegramUser). Inner body uses `peer.firstName`, `peer.lastName`, `peer.phone` — all TelegramUser fields. No reference to the outer EnginePeer? inside the if-body. Safe. |
| `.flatMap(EnginePeer.init)` simplification leaves wrong type | After migration, destructured `peer: EnginePeer?`. `.flatMap(EnginePeer.init)` would re-wrap to `EnginePeer?` (a no-op). Dropping is safe. |
| Pre-existing `import Postbox` removable from any of the 5 touched files | `import Postbox` should NOT be dropped speculatively — these files use Postbox for unrelated symbols (most consumers retain `Peer` references for non-DeviceContactInfoSubject paths). Defer Postbox-import drops to dedicated cleanup waves. |
## Wave shape
**Classification:** wave-91-pattern multi-module enum-payload + callback-signature migration.
**Iteration budget:** 1-3 (target 1; wave 91 took 2; this wave is similar size, slightly more complex).
**Subagent dispatch:** not needed — 17 edits in 5 files is single-implementer scope, but coordinator should review the diff carefully before commit given multi-module footprint.
## Verification
### Build
```sh
source ~/.zshrc 2>/dev/null; python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent \
--buildNumber=1 --configuration=debug_sim_arm64 --continueOnError
```
`--continueOnError` flag enabled given multi-module scope — surface all errors at once if iter-1 fails.
### Post-edit residue grep (expect specific patterns)
```sh
# Construction-site _asPeer drops complete:
grep -nE "subject:\s*\.(vcard|filter|create)\(.*_asPeer\(\)" \
submodules/PeerInfoUI/Sources/DeviceContactInfoController.swift \
submodules/TelegramUI/Components/Stories/StoryContainerScreen/Sources/StoryItemSetContainerViewSendMessage.swift \
submodules/TelegramUI/Sources/OpenChatMessage.swift
# Expected: empty.
# Completion _asPeer drops complete:
grep -nE "completion\(.*_asPeer\(\)" submodules/PeerInfoUI/Sources/DeviceContactInfoController.swift
# Expected: empty.
# .flatMap(EnginePeer.init) simplifications complete in DeviceContactInfoController:
grep -nE "peer\.flatMap\(EnginePeer\.init\)" submodules/PeerInfoUI/Sources/DeviceContactInfoController.swift
# Expected: empty.
# Downcast rewrite complete:
grep -nE "peer as\? TelegramUser" submodules/PeerInfoUI/Sources/DeviceContactInfoController.swift
# Expected: empty.
# ADD wraps present at the 2 Chat sites:
grep -nE "peerAndContactData\.0\.flatMap\(EnginePeer\.init\)" submodules/TelegramUI/Sources/ChatControllerOpenAttachmentMenu.swift
# Expected: 2 lines (683 and 1850, line numbers may shift slightly).
```
## Net delta projection
| Category | Count | Sites |
|---|---|---|
| `_asPeer()` drops at construction | −5 | DeviceContactInfoController:1289, 1443, 1489 + StoryItemSetContainerViewSendMessage:2132 + OpenChatMessage:443 |
| `_asPeer()` drops at completion calls | −2 | DeviceContactInfoController:1105, 1224 |
| `.flatMap(EnginePeer.init)` simplifications | −3 | DeviceContactInfoController:942, 944, 946 |
| `EnginePeer.init` wraps added (Pattern E) | +2 | ChatControllerOpenAttachmentMenu:683, 1850 |
| Downcast → case-let conversions | +1 | DeviceContactInfoController:849 |
| Type annotations migrated | 4 | AccountContext: 3 enum cases + 1 computed property |
**Net wrap delta:** **−8** (10 drops minus 2 adds).
## Out of scope
- `import Postbox` drops in any of the 5 touched files — they use Postbox for unrelated symbols. Defer to dedicated cleanup waves.
- Migrating the `peerAndContactData` upstream signal type from `(Peer?, DeviceContactExtendedData?)` to `(EnginePeer?, ...)` — would drop the 2 ADD bridges at Chat sites but cascades into multiple closures. Separate wave.
- `addContactToExisting`'s internal completion call sites — already typed `(EnginePeer?, ...)` per L1409, no migration needed in this wave.
## Memory file update
After landing, update `project_postbox_refactor_next_wave.md`:
- Add wave 105 outcome line into the recent-waves section.
- Mark `DeviceContactInfoSubject` candidate as drained.
- Note the wave-91-shape success — multi-module enum-payload migrations remain viable when pre-flight inventory clears layers 1-4.

172
docs/superpowers/specs/2026-04-26-postbox-wave-106-import-drop-sweep-design.md
View file

@ -1,172 +0,0 @@
# Postbox → TelegramEngine wave 106 — speculative `import Postbox` drop sweep (round 2)
## Context
Wave 93 (`72de7c4fd5`) ran the first speculative `import Postbox` drop sweep across the consumer modules in `submodules/`. It used a "drop blindly, restore on build feedback" methodology: 12 files dropped, 5 restored after the first build cycle, 7 net imports removed in a single commit.
Since wave 93, waves 94–105 have removed many further Postbox-typed references from consumer files (storeResourceData/moveResourceData/etc. drains, DeviceContactInfoSubject enum-payload migration, and several Shape-C/D mini-refactors). A second sweep should now find newly-orphaned `import Postbox` lines in files where the last Postbox reference was peeled off by an intervening wave.
This spec covers wave 106: the round-2 sweep applying the same methodology with an expanded pre-flight regex set incorporating wave 93's escape-case lessons.
## Goal
Drop `import Postbox` from any consumer-module Swift file in `submodules/` whose remaining content no longer references a Postbox-only symbol. Single atomic wave commit. No semantic code changes — only `import` and BUILD `deps` lines.
## Out of scope
- `submodules/Postbox/` (the module being phased out — never drop its self-references).
- `submodules/TelegramCore/` (different rules; TelegramCore must not `@_exported import Postbox` per wave-1 rule but its internal files retain `import Postbox` as needed).
- `submodules/TelegramApi/` (out of scope for the refactor).
- New typealiases or facade additions — wave 106 is import-cleanup-only.
- Code changes that swap a remaining Postbox-typed reference for an engine equivalent (those are dedicated waves).
## Methodology
### Step 1. Inventory candidates
```sh
grep -rl "^import Postbox" submodules --include="*.swift" \
| grep -v "^submodules/Postbox/" \
| grep -v "^submodules/TelegramCore/" \
| grep -v "^submodules/TelegramApi/" \
> /tmp/wave106-candidates.txt
```
Expected size: roughly 1100–1200 files based on wave-93-era counts adjusted for waves 94–105's drops.
### Step 2. Pattern-based preemptive restore
For each candidate file, skip (do NOT drop the import) if it contains any of the following regex patterns. The patterns are split into three tiers; matching ANY one is sufficient to skip.
**Tier 1 — hard Postbox infrastructure tokens:**
- `\bPostbox\b`
- `\bMediaBox\b`
- `\bMediaResource\b` (the protocol; `TelegramMediaResource` does not match because `\b` boundary)
- `\bMediaResourceData\b`
- `\bMediaResourceId\b`
- `\bPostboxCoding\b`
- `\bPostboxDecoder\b` (rarely escapes — `EnginePostboxDecoder` available, but file may still need import)
- `\bPostboxEncoder\b` (same)
- `\bMemoryBuffer\b` (same)
- `\bTempBoxFile\b`
- `\bValueBoxKey\b`
- `\bPostboxView\b`
- `\bcombinedView\b`
**Tier 2 — identifier types still defined in Postbox:**
- `\bPeerId\b`
- `\bMessageId\b`
- `\bMediaId\b`
- `\bMessageIndex\b`
- `\bMessageAndThreadId\b`
- `\bPeerNameIndex\b`
- `\bStoryId\b`
- `\bItemCollectionId\b`
- `\bFetchResourceSourceType\b`
- `\bFetchResourceError\b`
**Tier 3 — bare-name escapes (wave 93 lesson):**
- `\bPeer\b` (the protocol; `EnginePeer` and `TelegramPeer*` and `peer` lowercase do not match)
- `\bMessage\b` (the protocol/struct; `EngineMessage` and `TelegramMessage*` do not match)
- `\bMedia\b` (the protocol; `EngineMedia` and `TelegramMedia*` do not match)
Skip-list construction: build the regex by joining all three tiers with `|` and run a single `grep -E -l "<combined-regex>" $(cat /tmp/wave106-candidates.txt) > /tmp/wave106-skiplist.txt`. The drop-list is `comm -23 <(sort /tmp/wave106-candidates.txt) <(sort /tmp/wave106-skiplist.txt)`. Files in the skip-list keep their `import Postbox`. Over-skipping (false positives from comments or string literals) is safe — it just lowers yield; under-skipping is caught by the build feedback loop in steps 4-5.
### Step 3. Drop imports
For each file in `candidates - skip-list`, drop the `import Postbox` line via `Edit` (one Edit per file). All drops happen in a single batch before the first build — wave 93 validated that build feedback handles a large failure batch without manual triage difficulty (`grep "error:" /tmp/build.log | awk -F: '{print $1}' | sort -u` produces the restore list).
### Step 4. Build with `--continueOnError`
```sh
source ~/.zshrc 2>/dev/null; \
python3 build-system/Make/Make.py --overrideXcodeVersion \
--cacheDir ~/telegram-bazel-cache \
build \
--configurationPath build-system/appstore-configuration.json \
--gitCodesigningRepository git@gitlab.com:peter-iakovlev/fastlanematch.git \
--gitCodesigningType development --gitCodesigningUseCurrent --buildNumber=1 \
--configuration=debug_sim_arm64 \
--continueOnError 2>&1 | tee /tmp/wave106-build-iter1.log
```
Parse the log for `error:` lines. Group by file path; restore `import Postbox` to any file with a missing-symbol error.
### Step 5. Iterate
Re-run the build. Repeat restore-and-rebuild until clean. Halt-on-iter-5 (see halt conditions).
### Step 6. Final clean build (no `--continueOnError`)
Confirm green build to validate that no inter-module ordering issue was masked.
### Step 7. BUILD-dep sweep (optional, if time permits)
For each Bazel package whose Swift sources no longer reference `import Postbox`:
```sh
# enumerate packages with no remaining Postbox imports
for build in $(find submodules -name BUILD); do
pkg_dir=$(dirname "$build")
if ! grep -rq "^import Postbox" "$pkg_dir" --include="*.swift" 2>/dev/null; then
if grep -q "//submodules/Postbox" "$build"; then
echo "$build"
fi
fi
done
```
For each match: drop the `//submodules/Postbox` entry from the package's `BUILD` `deps` list. Re-run the full clean build to confirm.
### Step 8. Single commit
All file edits and BUILD changes land in one commit:
```
Postbox -> TelegramEngine wave 106 (import drop sweep round 2)
Speculative drop of `import Postbox` in N files where the last
Postbox-typed symbol reference was peeled off by waves 94-105.
Methodology: pattern-based pre-flight skip + drop + build feedback +
restore loop (wave-93-validated recipe). M files restored after build.
+ K BUILD deps removed.
```
## Halt conditions
1. **Scope drift to TelegramCore/Postbox/TelegramApi.** If build errors surface in any of these three modules, halt immediately and `git reset --hard` the wave. The candidate filter is wrong somewhere.
2. **First-pass failure rate > 50%.** Indicates the pre-flight regex set is missing a major escape pattern. Halt, analyze the failure cluster, expand regex, re-run from step 2.
3. **Iteration count > 5.** Diminishing returns; commit what is green and defer the rest to wave 107.
## Pre-flight WIP check
Before any edits:
```sh
git status --short | grep -v "^??" | grep -v "^ m build-system/bazel-rules/sourcekit-bazel-bsp"
```
If output is non-empty, halt — there is unrelated WIP that would get tangled. The known persistent state (untracked `build-system/tulsi/`, `submodules/TgVoip/`, `third-party/libx264/` and the `m` submodule marker) is acceptable and recorded in memory.
## Expected outcome
- 5–30 net `import Postbox` drops in `submodules/`.
- 0–3 BUILD `deps` removals.
- 2–3 build iterations.
- Single commit.
- Wall-clock 30–90 min.
## Risks
- **Regex misses bare type names** → caught by build feedback at cost of 1 extra cycle. Acceptable.
- **A file holds a Postbox reference only inside a comment** that the regex doesn't distinguish from real code → safe (false positive: file would have been skipped unnecessarily; sweep just leaves the import in).
- **Cross-file dependency where dropping module A's import breaks module B compilation** → caught by build cycle; restore in the failing module.
- **Bazel cache state inconsistency** → unlikely with `--cacheDir ~/telegram-bazel-cache` already in steady state, but if surfaces, full clean build will catch it.
## Success criteria
- `git diff --stat` shows only `import Postbox` line removals (and possibly BUILD `deps` line removals).
- Final clean build (no `--continueOnError`) is green.
- No file outside `submodules/` modified.
- No file in `submodules/Postbox/`, `submodules/TelegramCore/`, or `submodules/TelegramApi/` modified.
- Memory file `project_postbox_refactor_next_wave.md` updated to record the wave outcome.

1
submodules/AccountContext/Sources/ChatController.swift
View file

@ -1117,6 +1117,7 @@ public protocol ChatController: ViewController {
func activateSearch(domain: ChatSearchDomain, query: String)
func activateInput(type: ChatControllerActivateInput)
func beginClearHistory(type: InteractiveHistoryClearingType)
func presentReactionDeletionOptions(author: Peer, messageId: MessageId)
func performScrollToTop() -> Bool
func transferScrollingVelocity(_ velocity: CGFloat)

1
submodules/AccountContext/Sources/GalleryController.swift
View file

@ -10,6 +10,7 @@ public enum GalleryMediaSubject: Hashable {
case pollDescription
case pollOption(Data)
case pollSolution
case instantPageMedia(MediaId)
}
public enum GalleryControllerItemSource {

2
submodules/AccountContext/Sources/Premium.swift
View file

@ -45,7 +45,7 @@ public enum PremiumIntroSource {
case todo
case copyProtection
case aiTools
case auth(String)
case auth(String, Int32)
case premiumGift(TelegramMediaFile)
}

8
submodules/AuthorizationUI/Sources/AuthorizationSequenceController.swift
View file

@ -810,8 +810,8 @@ public final class AuthorizationSequenceController: NavigationController, ASAuth
return controller
}
private func paymentController(number: String, phoneCodeHash: String, storeProduct: String, supportEmailAddress: String, supportEmailSubject: String) -> AuthorizationSequencePaymentScreen {
let controller = AuthorizationSequencePaymentScreen(sharedContext: self.sharedContext, engine: self.engine, presentationData: self.presentationData, inAppPurchaseManager: self.inAppPurchaseManager, phoneNumber: number, phoneCodeHash: phoneCodeHash, storeProduct: storeProduct, supportEmailAddress: supportEmailAddress, supportEmailSubject: supportEmailSubject, back: { [weak self] in
private func paymentController(number: String, phoneCodeHash: String, storeProduct: String, premiumDays: Int32, supportEmailAddress: String, supportEmailSubject: String) -> AuthorizationSequencePaymentScreen {
let controller = AuthorizationSequencePaymentScreen(sharedContext: self.sharedContext, engine: self.engine, presentationData: self.presentationData, inAppPurchaseManager: self.inAppPurchaseManager, phoneNumber: number, phoneCodeHash: phoneCodeHash, storeProduct: storeProduct, premiumDays: premiumDays, supportEmailAddress: supportEmailAddress, supportEmailSubject: supportEmailSubject, back: { [weak self] in
guard let self else {
return
}
@ -1348,12 +1348,12 @@ public final class AuthorizationSequenceController: NavigationController, ASAuth
}
controllers.append(self.signUpController(firstName: firstName, lastName: lastName, termsOfService: termsOfService, displayCancel: displayCancel))
self.setViewControllers(controllers, animated: !self.viewControllers.isEmpty)
case let .payment(number, codeHash, storeProduct, supportEmailAddress, supportEmailSubject, _):
case let .payment(number, codeHash, storeProduct, premiumDays, supportEmailAddress, supportEmailSubject, _):
var controllers: [ViewController] = []
if !self.otherAccountPhoneNumbers.1.isEmpty {
controllers.append(self.splashController())
}
controllers.append(self.paymentController(number: number, phoneCodeHash: codeHash, storeProduct: storeProduct, supportEmailAddress: supportEmailAddress, supportEmailSubject: supportEmailSubject))
controllers.append(self.paymentController(number: number, phoneCodeHash: codeHash, storeProduct: storeProduct, premiumDays: premiumDays, supportEmailAddress: supportEmailAddress, supportEmailSubject: supportEmailSubject))
self.setViewControllers(controllers, animated: !self.viewControllers.isEmpty)
}
}

69
submodules/AuthorizationUI/Sources/AuthorizationSequencePaymentScreen.swift
View file

@ -28,6 +28,7 @@ import PhoneNumberFormat
import PlainButtonComponent
import StoreKit
import DeviceModel
import GlassBarButtonComponent
final class AuthorizationSequencePaymentScreenComponent: Component {
typealias EnvironmentType = ViewControllerComponentContainer.Environment
@ -39,6 +40,7 @@ final class AuthorizationSequencePaymentScreenComponent: Component {
let phoneNumber: String
let phoneCodeHash: String
let storeProduct: String
let premiumDays: Int32
let supportEmailAddress: String
let supportEmailSubject: String
@ -50,6 +52,7 @@ final class AuthorizationSequencePaymentScreenComponent: Component {
phoneNumber: String,
phoneCodeHash: String,
storeProduct: String,
premiumDays: Int32,
supportEmailAddress: String,
supportEmailSubject: String
) {
@ -60,6 +63,7 @@ final class AuthorizationSequencePaymentScreenComponent: Component {
self.phoneNumber = phoneNumber
self.phoneCodeHash = phoneCodeHash
self.storeProduct = storeProduct
self.premiumDays = premiumDays
self.supportEmailAddress = supportEmailAddress
self.supportEmailSubject = supportEmailSubject
}
@ -115,7 +119,7 @@ final class AuthorizationSequencePaymentScreenComponent: Component {
self.state?.updated()
let (currency, amount) = storeProduct.priceCurrencyAndAmount
let purpose: AppStoreTransactionPurpose = .authCode(restore: false, phoneNumber: component.phoneNumber, phoneCodeHash: component.phoneCodeHash, currency: currency, amount: amount)
let purpose: AppStoreTransactionPurpose = .authCode(restore: false, phoneNumber: component.phoneNumber, phoneCodeHash: component.phoneCodeHash, premiumDays: component.premiumDays, currency: currency, amount: amount)
let _ = (component.engine.payments.canPurchasePremium(purpose: purpose)
|> deliverOnMainQueue).start(next: { [weak self] available in
guard let self else {
@ -251,25 +255,27 @@ final class AuthorizationSequencePaymentScreenComponent: Component {
let helpButtonSize = self.helpButton.update(
transition: transition,
component: AnyComponent(PlainButtonComponent(
content: AnyComponent(MultilineTextComponent(
text: .plain(NSAttributedString(string: environment.strings.Login_PhoneNumberHelp, font: Font.regular(17.0), textColor: environment.theme.list.itemAccentColor))
)),
minSize: CGSize(width: 0.0, height: 44.0),
contentInsets: UIEdgeInsets(top: 0.0, left: 8.0, bottom: 0.0, right: 8.0),
action: { [weak self] in
guard let self else {
return
component: AnyComponent(
GlassBarButtonComponent(
size: nil,
backgroundColor: nil,
isDark: environment.theme.overallDarkAppearance,
state: .glass,
component: AnyComponentWithIdentity(id: "label", component: AnyComponent(MultilineTextComponent(
text: .plain(NSAttributedString(string: environment.strings.Login_PhoneNumberHelp, font: Font.regular(17.0), textColor: environment.theme.chat.inputPanel.panelControlColor))
))),
action: { [weak self] _ in
guard let self else {
return
}
self.displaySendEmail(error: nil, errorCode: nil)
}
self.displaySendEmail(error: nil, errorCode: nil)
},
animateScale: false,
animateContents: false
)),
)
),
environment: {},
containerSize: CGSize(width: 200.0, height: 100.0)
containerSize: CGSize(width: 200.0, height: 44.0)
)
let helpButtonFrame = CGRect(origin: CGPoint(x: availableSize.width - 8.0 - helpButtonSize.width, y: environment.statusBarHeight), size: helpButtonSize)
let helpButtonFrame = CGRect(origin: CGPoint(x: availableSize.width - 16.0 - helpButtonSize.width, y: environment.navigationHeight - helpButtonSize.height - 6.0), size: helpButtonSize)
if let helpButtonView = self.helpButton.view {
if helpButtonView.superview == nil {
self.addSubview(helpButtonView)
@ -333,13 +339,24 @@ final class AuthorizationSequencePaymentScreenComponent: Component {
))
)
)
let supportText: String
if component.premiumDays == 7 {
supportText = environment.strings.Login_Fee_Support_Text
} else if component.premiumDays > 0 {
let daysString = environment.strings.Login_Fee_Support_NewText_Days(component.premiumDays)
supportText = environment.strings.Login_Fee_Support_NewText(daysString).string
} else {
supportText = environment.strings.Login_Fee_Support_NewTextNone
}
items.append(
AnyComponentWithIdentity(
id: "support",
component: AnyComponent(ParagraphComponent(
title: environment.strings.Login_Fee_Support_Title,
titleColor: textColor,
text: environment.strings.Login_Fee_Support_Text,
text: supportText,
textColor: secondaryTextColor,
iconName: "Premium/Authorization/Support",
iconColor: linkColor,
@ -351,7 +368,7 @@ final class AuthorizationSequencePaymentScreenComponent: Component {
sharedContext: component.sharedContext,
engine: component.engine,
inAppPurchaseManager: component.inAppPurchaseManager,
source: .auth(product.price),
source: .auth(product.price, component.premiumDays),
proceed: { [weak self] in
self?.proceed()
}
@ -410,6 +427,16 @@ final class AuthorizationSequencePaymentScreenComponent: Component {
}
let buttonString = environment.strings.Login_Fee_SignUp(priceString).string
let buttonSubtitle: String
if component.premiumDays == 7 {
buttonSubtitle = environment.strings.Login_Fee_GetPremiumForAWeek
} else if component.premiumDays > 0 {
let daysString = environment.strings.Login_Fee_GetPremiumForDays_Days(component.premiumDays)
buttonSubtitle = environment.strings.Login_Fee_GetPremiumForDays(daysString).string
} else {
buttonSubtitle = environment.strings.Login_Fee_GetPremiumNone
}
let buttonAttributedString = NSMutableAttributedString(string: buttonString, font: Font.semibold(17.0), textColor: environment.theme.list.itemCheckColors.foregroundColor, paragraphAlignment: .center)
let buttonSize = self.button.update(
transition: transition,
@ -425,7 +452,7 @@ final class AuthorizationSequencePaymentScreenComponent: Component {
component: AnyComponent(
VStack([
AnyComponentWithIdentity(id: AnyHashable(0), component: AnyComponent(MultilineTextComponent(text: .plain(buttonAttributedString)))),
AnyComponentWithIdentity(id: AnyHashable(1), component: AnyComponent(MultilineTextComponent(text: .plain(NSAttributedString(string: environment.strings.Login_Fee_GetPremiumForAWeek, font: Font.medium(11.0), textColor: environment.theme.list.itemCheckColors.foregroundColor.withAlphaComponent(0.7), paragraphAlignment: .center)))))
AnyComponentWithIdentity(id: AnyHashable(1), component: AnyComponent(MultilineTextComponent(text: .plain(NSAttributedString(string: buttonSubtitle, font: Font.medium(11.0), textColor: environment.theme.list.itemCheckColors.foregroundColor.withAlphaComponent(0.7), paragraphAlignment: .center)))))
], spacing: 1.0)
)
),
@ -467,6 +494,7 @@ public final class AuthorizationSequencePaymentScreen: ViewControllerComponentCo
phoneNumber: String,
phoneCodeHash: String,
storeProduct: String,
premiumDays: Int32,
supportEmailAddress: String,
supportEmailSubject: String,
back: @escaping () -> Void
@ -479,6 +507,7 @@ public final class AuthorizationSequencePaymentScreen: ViewControllerComponentCo
phoneNumber: phoneNumber,
phoneCodeHash: phoneCodeHash,
storeProduct: storeProduct,
premiumDays: premiumDays,
supportEmailAddress: supportEmailAddress,
supportEmailSubject: supportEmailSubject
), navigationBarAppearance: .transparent, theme: .default, updatedPresentationData: (initial: presentationData, signal: .single(presentationData)))

11
submodules/BrowserUI/Sources/BrowserBookmarksScreen.swift
View file

@ -83,6 +83,7 @@ public final class BrowserBookmarksScreen: ViewController {
controller.openUrl(url.url)
controller.dismiss()
}
}, openExternalInstantPage: { _ in
}, shareCurrentLocation: {
}, shareAccountContact: {
}, sendBotCommand: { _, _ in
@ -176,10 +177,11 @@ public final class BrowserBookmarksScreen: ViewController {
}, sendGift: { _ in
}, openUniqueGift: { _ in
}, openMessageFeeException: {
}, requestMessageUpdate: { _, _ in
}, requestMessageUpdate: { _, _, _ in
}, cancelInteractiveKeyboardGestures: {
}, dismissTextInput: {
}, scrollToMessageId: { _ in
}, scrollToMessageId: { _, _ in
}, scrollToMessageIdWithAnchor: { _, _ in
}, navigateToStory: { _, _ in
}, attemptedNavigationToPrivateQuote: { _ in
}, forceUpdateWarpContents: {
@ -189,7 +191,10 @@ public final class BrowserBookmarksScreen: ViewController {
}, requestToggleTodoMessageItem: { _, _, _ in
}, displayTodoToggleUnavailable: { _ in
}, openStarsPurchase: { _ in
}, openRankInfo: { _, _, _ in }, openSetPeerAvatar: {}, automaticMediaDownloadSettings: MediaAutoDownloadSettings.defaultSettings, pollActionState: ChatInterfacePollActionState(), stickerSettings: ChatInterfaceStickerSettings(), presentationContext: ChatPresentationContext(context: context, backgroundNode: nil))
}, openRankInfo: { _, _, _ in
}, openSetPeerAvatar: {
}, displayPollRestrictedToast: { _ in
}, automaticMediaDownloadSettings: MediaAutoDownloadSettings.defaultSettings, pollActionState: ChatInterfacePollActionState(), stickerSettings: ChatInterfaceStickerSettings(), presentationContext: ChatPresentationContext(context: context, backgroundNode: nil))
let tagMask: MessageTags = .webPage

3
submodules/BrowserUI/Sources/BrowserInstantPageContent.swift
View file

@ -401,6 +401,7 @@ final class BrowserInstantPageContent: UIView, BrowserContent, UIScrollViewDeleg
self.settings = InstantPagePresentationSettings(
themeType: self.presentationData.theme.overallDarkAppearance ? .dark : .light,
fontSize: fontSize,
lineSpacingFactor: 1.0,
forceSerif: state.isSerif,
autoNightMode: false,
ignoreAutoNightModeUntil: 0
@ -498,7 +499,7 @@ final class BrowserInstantPageContent: UIView, BrowserContent, UIScrollViewDeleg
return
}
let currentLayout = instantPageLayoutForWebPage(webPage, instantPage: instantPage, userLocation: self.sourceLocation.userLocation, boundingWidth: size.width, safeInset: insets.left, strings: self.presentationData.strings, theme: self.theme, dateTimeFormat: self.presentationData.dateTimeFormat, webEmbedHeights: self.currentWebEmbedHeights, cachedMessageSyntaxHighlight: self.codeHighlight)
let currentLayout = instantPageLayoutForWebPage(webPage, instantPage: instantPage, userLocation: self.sourceLocation.userLocation, boundingWidth: size.width, sideInset: 17.0, safeInset: insets.left, strings: self.presentationData.strings, theme: self.theme, dateTimeFormat: self.presentationData.dateTimeFormat, webEmbedHeights: self.currentWebEmbedHeights, cachedMessageSyntaxHighlight: self.codeHighlight)
let currentLayoutTiles = instantPageTilesFromLayout(currentLayout, boundingWidth: size.width)

10
submodules/BrowserUI/Sources/BrowserMarkdown.swift
View file

@ -20,6 +20,7 @@ private let markdownInlineHTMLInlineIntent = InlinePresentationIntent(rawValue:
private let markdownDefaultBlockImageDimensions = PixelDimensions(width: 1200, height: 900)
private let markdownDefaultInlineImageDimensions = PixelDimensions(width: 18, height: 18)
private let markdownImageParsingEnabled = false
private let markdownTaskListUncheckedNumber = "\u{001f}tg-md-task:unchecked"
private let markdownTaskListCheckedNumber = "\u{001f}tg-md-task:checked"
private let markdownRawHTMLTagRegex = try! NSRegularExpression(pattern: #"</?([A-Za-z][A-Za-z0-9:-]*)\b[^>]*?>"#)
@ -42,7 +43,7 @@ private let markdownVoidHTMLTags: Set<String> = [
]
private struct MarkdownSafetyLimits {
let maxFileSize = 2_097_152
let maxFileSize = 524_288
let maxLineLength = 32_768
let maxBlockquoteDepth = 64
let maxListIndent = 96
@ -353,6 +354,9 @@ private final class MarkdownConversionContext {
}
func resolveImage(attributes: [NSAttributedString.Key: Any]) -> MarkdownResolvedImage? {
guard markdownImageParsingEnabled else {
return nil
}
guard let imageUrl = markdownImageURL(attributes: attributes) else {
return nil
}
@ -1166,10 +1170,8 @@ private func markdownBlocks(from node: MarkdownIntentNode, context: MarkdownConv
switch level {
case Int.min ... 1:
return [.title(text)]
case 2:
return [.header(text)]
default:
return [.heading(text: text, level: Int32(max(3, min(level, 6))))]
return [.heading(text: text, level: Int32(max(2, min(level, 6))))]
}
case .paragraph:
guard let inlineContent = markdownInlineContent(from: node.attributedText, context: context) else {

28
submodules/Camera/Sources/Camera.swift
View file

@ -146,7 +146,7 @@ private final class CameraContext {
transform = CGAffineTransformTranslate(transform, 0.0, -size.height)
ciImage = ciImage.transformed(by: transform)
}
ciImage = ciImage.clampedToExtent().applyingGaussianBlur(sigma: Camera.isDualCameraSupported(forRoundVideo: true) ? 100.0 : 40.0).cropped(to: CGRect(origin: .zero, size: size))
ciImage = ciImage.clampedToExtent().applyingGaussianBlur(sigma: Camera.isDualCameraSupported(forRoundVideo: true) ? 60.0 : 40.0).cropped(to: CGRect(origin: .zero, size: size))
if let cgImage = self.ciContext.createCGImage(ciImage, from: ciImage.extent) {
let uiImage = UIImage(cgImage: cgImage, scale: 1.0, orientation: .right)
if front {
@ -189,6 +189,7 @@ private final class CameraContext {
deinit {
Logger.shared.log("CameraContext", "deinit")
NotificationCenter.default.removeObserver(self)
}
private var isSessionRunning = false
@ -202,7 +203,7 @@ private final class CameraContext {
}
func stopCapture(invalidate: Bool = false) {
Logger.shared.log("CameraContext", "startCapture(invalidate: \(invalidate))")
Logger.shared.log("CameraContext", "stopCapture(invalidate: \(invalidate))")
if invalidate {
self.mainDeviceContext?.device.resetZoom()
@ -212,6 +213,7 @@ private final class CameraContext {
}
self.session.session.stopRunning()
self.isSessionRunning = false
}
func focus(at point: CGPoint, autoFocus: Bool) {
@ -228,7 +230,7 @@ private final class CameraContext {
}
func setFps(_ fps: Float64) {
self.mainDeviceContext?.device.fps = fps
self.mainDeviceContext?.device.setFps(fps)
}
private var modeChange: Camera.ModeChange = .none {
@ -276,7 +278,6 @@ private final class CameraContext {
self._positionPromise.set(targetPosition)
self.modeChange = .position
let preferWide = self.initialConfiguration.preferWide || isRoundVideo
let preferLowerFramerate = self.initialConfiguration.preferLowerFramerate || isRoundVideo
@ -565,6 +566,11 @@ private final class CameraContext {
return .finished(mainImage, additionalImage, CACurrentMediaTime())
}
} else {
if case .failed = main {
return .failed
} else if case .failed = additional {
return .failed
}
return .began
}
} |> distinctUntilChanged
@ -583,6 +589,10 @@ private final class CameraContext {
mainDeviceContext.device.setTorchMode(self._flashMode)
}
let timestamp = CACurrentMediaTime() + 2.0
self.lastSnapshotTimestamp = timestamp
self.lastAdditionalSnapshotTimestamp = timestamp
let orientation = self.simplePreviewView?.videoPreviewLayer.connection?.videoOrientation ?? .portrait
if self.initialConfiguration.isRoundVideo {
return mainDeviceContext.output.startRecording(mode: .roundVideo, orientation: DeviceModel.current.isIpad ? orientation : .portrait, additionalOutput: self.additionalDeviceContext?.output)
@ -788,6 +798,11 @@ public final class Camera {
secondaryPreviewView.setSession(session.session, autoConnect: false)
}
if #available(iOS 14.5, *), configuration.isRoundVideo {
AVCaptureDevice.centerStageControlMode = .app
AVCaptureDevice.isCenterStageEnabled = false
}
self.queue.async {
let context = CameraContext(queue: self.queue, session: session, configuration: configuration, metrics: self.metrics, previewView: previewView, secondaryPreviewView: secondaryPreviewView)
self.contextRef = Unmanaged.passRetained(context)
@ -801,6 +816,10 @@ public final class Camera {
self.queue.async {
contextRef?.release()
}
if #available(iOS 14.5, *) {
AVCaptureDevice.centerStageControlMode = .user
}
}
public func startCapture() {
@ -1170,6 +1189,7 @@ public struct CameraRecordingData {
}
public enum CameraRecordingError {
case videoRecorderInitializationError
case audioInitializationError
}

44
submodules/Camera/Sources/CameraDevice.swift
View file

@ -141,10 +141,12 @@ final class CameraDevice {
Logger.shared.log("Camera", "No format selected")
}
#if DEBUG
Logger.shared.log("Camera", "Available formats:")
for format in device.formats {
Logger.shared.log("Camera", format.description)
}
#endif
if let targetFPS = device.actualFPS(maxFramerate) {
device.activeVideoMinFrameDuration = targetFPS.duration
@ -154,7 +156,7 @@ final class CameraDevice {
if device.isLowLightBoostSupported {
device.automaticallyEnablesLowLightBoostWhenAvailable = true
}
if device.isExposureModeSupported(.continuousAutoExposure) {
device.exposureMode = .continuousAutoExposure
}
@ -180,18 +182,16 @@ final class CameraDevice {
self.setFocusPoint(CGPoint(x: 0.5, y: 0.5), focusMode: .continuousAutoFocus, exposureMode: .continuousAutoExposure, monitorSubjectAreaChange: false)
}
var fps: Double = defaultFPS {
didSet {
guard let device = self.videoDevice, let targetFPS = device.actualFPS(Double(self.fps)) else {
return
}
self.fps = targetFPS.fps
self.transaction(device) { device in
device.activeVideoMinFrameDuration = targetFPS.duration
device.activeVideoMaxFrameDuration = targetFPS.duration
}
private(set) var fps: Double = defaultFPS
func setFps(_ fps: Double) {
guard let device = self.videoDevice, let targetFPS = device.actualFPS(Double(fps)) else {
return
}
self.fps = targetFPS.fps
self.transaction(device) { device in
device.activeVideoMinFrameDuration = targetFPS.duration
device.activeVideoMaxFrameDuration = targetFPS.duration
}
}
@ -305,7 +305,8 @@ final class CameraDevice {
return
}
self.transaction(device) { device in
device.videoZoomFactor = max(device.neutralZoomFactor, min(10.0, device.neutralZoomFactor + zoomLevel))
let target = device.neutralZoomFactor + zoomLevel
device.videoZoomFactor = self.clampedZoomFactor(target, for: device)
}
}
@ -314,7 +315,8 @@ final class CameraDevice {
return
}
self.transaction(device) { device in
device.videoZoomFactor = max(1.0, min(10.0, device.videoZoomFactor * zoomDelta))
let target = device.videoZoomFactor * zoomDelta
device.videoZoomFactor = self.clampedZoomFactor(target, for: device)
}
}
@ -323,7 +325,8 @@ final class CameraDevice {
return
}
self.transaction(device) { device in
device.ramp(toVideoZoomFactor: zoomLevel, withRate: Float(rate))
let target = self.clampedZoomFactor(zoomLevel, for: device)
device.ramp(toVideoZoomFactor: target, withRate: Float(rate))
}
}
@ -332,7 +335,14 @@ final class CameraDevice {
return
}
self.transaction(device) { device in
device.videoZoomFactor = neutral ? device.neutralZoomFactor : device.minAvailableVideoZoomFactor
let target = neutral ? device.neutralZoomFactor : device.minAvailableVideoZoomFactor
device.videoZoomFactor = self.clampedZoomFactor(target, for: device)
}
}
private func clampedZoomFactor(_ value: CGFloat, for device: AVCaptureDevice) -> CGFloat {
let minimum = max(1.0, device.minAvailableVideoZoomFactor)
let maximum = max(minimum, device.maxAvailableVideoZoomFactor)
return min(maximum, max(minimum, value))
}
}

13
submodules/Camera/Sources/CameraInput.swift
View file

@ -15,11 +15,14 @@ class CameraInput {
}
func invalidate(for session: CameraSession, switchAudio: Bool = true) {
for input in session.session.inputs {
if !switchAudio && input === self.audioInput {
continue
}
session.session.removeInput(input)
if let videoInput = self.videoInput, session.session.inputs.contains(where: { $0 === videoInput }) {
session.session.removeInput(videoInput)
}
self.videoInput = nil
if switchAudio, let audioInput = self.audioInput, session.session.inputs.contains(where: { $0 === audioInput }) {
session.session.removeInput(audioInput)
self.audioInput = nil
}
}

111
submodules/Camera/Sources/CameraOutput.swift
View file

@ -93,6 +93,11 @@ public struct CameraCode: Equatable {
}
final class CameraOutput: NSObject {
private struct RoundVideoFormatDescriptionCacheEntry {
let sourceFormatDescription: CMFormatDescription
let outputFormatDescription: CMFormatDescription
}
let exclusive: Bool
let ciContext: CIContext
let colorSpace: CGColorSpace
@ -111,13 +116,14 @@ final class CameraOutput: NSObject {
private var roundVideoFilter: CameraRoundLegacyVideoFilter?
private let semaphore = DispatchSemaphore(value: 1)
private var roundVideoFormatDescriptionCache: [RoundVideoFormatDescriptionCacheEntry] = []
private let videoQueue = DispatchQueue(label: "", qos: .userInitiated)
private let audioQueue = DispatchQueue(label: "")
private let metadataQueue = DispatchQueue(label: "")
private var photoCaptureRequests: [Int64: PhotoCaptureContext] = [:]
private var photoCaptureRequests = Atomic<[Int64: PhotoCaptureContext]>(value: [:])
private var videoRecorder: VideoRecorder?
private var captureOrientation: AVCaptureVideoOrientation = .portrait
@ -186,9 +192,9 @@ final class CameraOutput: NSObject {
}
if #available(iOS 13.0, *), session.hasMultiCam {
if let device = device.videoDevice, let ports = input.videoInput?.ports(for: AVMediaType.video, sourceDeviceType: device.deviceType, sourceDevicePosition: device.position) {
if let device = device.videoDevice, let ports = input.videoInput?.ports(for: AVMediaType.video, sourceDeviceType: device.deviceType, sourceDevicePosition: device.position), let firstPort = ports.first {
if let previewView {
let previewConnection = AVCaptureConnection(inputPort: ports.first!, videoPreviewLayer: previewView.videoPreviewLayer)
let previewConnection = AVCaptureConnection(inputPort: firstPort, videoPreviewLayer: previewView.videoPreviewLayer)
if session.session.canAddConnection(previewConnection) {
session.session.addConnection(previewConnection)
self.previewConnection = previewConnection
@ -268,8 +274,8 @@ final class CameraOutput: NSObject {
return EmptyDisposable
}
subscriber.putNext(self.photoOutput.isFlashScene)
let observer = self.photoOutput.observe(\.isFlashScene, options: [.new], changeHandler: { device, _ in
subscriber.putNext(self.photoOutput.isFlashScene)
let observer = self.photoOutput.observe(\.isFlashScene, options: [.new], changeHandler: { output, _ in
subscriber.putNext(output.isFlashScene)
})
return ActionDisposable {
observer.invalidate()
@ -316,12 +322,20 @@ final class CameraOutput: NSObject {
#else
let uniqueId = settings.uniqueID
let photoCapture = PhotoCaptureContext(ciContext: self.ciContext, settings: settings, orientation: orientation, mirror: mirror)
self.photoCaptureRequests[uniqueId] = photoCapture
let _ = self.photoCaptureRequests.modify { dict in
var dict = dict
dict[uniqueId] = photoCapture
return dict
}
self.photoOutput.capturePhoto(with: settings, delegate: photoCapture)
return photoCapture.signal
|> afterDisposed { [weak self] in
self?.photoCaptureRequests.removeValue(forKey: uniqueId)
let _ = self?.photoCaptureRequests.modify { dict in
var dict = dict
dict.removeValue(forKey: uniqueId)
return dict
}
}
#endif
}
@ -419,18 +433,21 @@ final class CameraOutput: NSObject {
}
}
)
guard let videoRecorder else {
return .fail(.videoRecorderInitializationError)
}
videoRecorder?.start()
videoRecorder.start()
self.videoRecorder = videoRecorder
if case .dualCamera = mode, let position {
videoRecorder?.markPositionChange(position: position, time: .zero)
videoRecorder.markPositionChange(position: position, time: .zero)
} else if case .roundVideo = mode {
additionalOutput?.masterOutput = self
}
return Signal { subscriber in
let timer = SwiftSignalKit.Timer(timeout: 0.033, repeat: true, completion: { [weak videoRecorder] in
let timer = SwiftSignalKit.Timer(timeout: 0.09, repeat: true, completion: { [weak videoRecorder] in
let recordingData = CameraRecordingData(duration: videoRecorder?.duration ?? 0.0, filePath: outputFilePath)
subscriber.putNext(recordingData)
}, queue: Queue.mainQueue())
@ -463,6 +480,43 @@ final class CameraOutput: NSObject {
private var lastSampleTimestamp: CMTime?
private func roundVideoFormatDescription(for sourceFormatDescription: CMFormatDescription) -> CMFormatDescription? {
if let entry = self.roundVideoFormatDescriptionCache.first(where: { CFEqual($0.sourceFormatDescription, sourceFormatDescription) }) {
return entry.outputFormatDescription
}
guard let extensions = CMFormatDescriptionGetExtensions(sourceFormatDescription) as? [String: Any] else {
return nil
}
let mediaSubType = CMFormatDescriptionGetMediaSubType(sourceFormatDescription)
var updatedExtensions = extensions
updatedExtensions["CVBytesPerRow"] = videoMessageDimensions.width * 4
var outputFormatDescription: CMFormatDescription?
let status = CMVideoFormatDescriptionCreate(
allocator: nil,
codecType: mediaSubType,
width: videoMessageDimensions.width,
height: videoMessageDimensions.height,
extensions: updatedExtensions as CFDictionary,
formatDescriptionOut: &outputFormatDescription
)
guard status == noErr, let outputFormatDescription else {
return nil
}
self.roundVideoFormatDescriptionCache.append(RoundVideoFormatDescriptionCacheEntry(
sourceFormatDescription: sourceFormatDescription,
outputFormatDescription: outputFormatDescription
))
if self.roundVideoFormatDescriptionCache.count > 4 {
self.roundVideoFormatDescriptionCache.removeFirst(self.roundVideoFormatDescriptionCache.count - 4)
}
return outputFormatDescription
}
private var needsCrossfadeTransition = false
private var crossfadeTransitionStart: Double = 0.0
@ -564,17 +618,11 @@ final class CameraOutput: NSObject {
return nil
}
self.semaphore.wait()
let mediaSubType = CMFormatDescriptionGetMediaSubType(formatDescription)
let extensions = CMFormatDescriptionGetExtensions(formatDescription) as! [String: Any]
var updatedExtensions = extensions
updatedExtensions["CVBytesPerRow"] = videoMessageDimensions.width * 4
var newFormatDescription: CMFormatDescription?
var status = CMVideoFormatDescriptionCreate(allocator: nil, codecType: mediaSubType, width: videoMessageDimensions.width, height: videoMessageDimensions.height, extensions: updatedExtensions as CFDictionary, formatDescriptionOut: &newFormatDescription)
guard status == noErr, let newFormatDescription else {
defer {
self.semaphore.signal()
}
guard let newFormatDescription = self.roundVideoFormatDescription(for: formatDescription) else {
return nil
}
@ -585,12 +633,11 @@ final class CameraOutput: NSObject {
filter = CameraRoundLegacyVideoFilter(ciContext: self.ciContext, colorSpace: self.colorSpace, simple: self.exclusive)
self.roundVideoFilter = filter
}
if !filter.isPrepared {
if !filter.isPrepared || filter.inputFormatDescription.map({ !CFEqual($0, newFormatDescription) }) ?? true {
filter.prepare(with: newFormatDescription, outputRetainedBufferCountHint: 4)
}
guard let newPixelBuffer = filter.render(pixelBuffer: videoPixelBuffer, additional: additional, captureOrientation: self.captureOrientation, transitionFactor: transitionFactor) else {
self.semaphore.signal()
return nil
}
@ -603,7 +650,7 @@ final class CameraOutput: NSObject {
}
var newSampleBuffer: CMSampleBuffer?
status = CMSampleBufferCreateForImageBuffer(
let status = CMSampleBufferCreateForImageBuffer(
allocator: kCFAllocatorDefault,
imageBuffer: newPixelBuffer,
dataReady: true,
@ -615,10 +662,8 @@ final class CameraOutput: NSObject {
)
if status == noErr, let newSampleBuffer {
self.semaphore.signal()
return newSampleBuffer
}
self.semaphore.signal()
return nil
}
@ -640,23 +685,23 @@ extension CameraOutput: AVCaptureVideoDataOutputSampleBufferDelegate, AVCaptureA
guard CMSampleBufferDataIsReady(sampleBuffer) else {
return
}
if let videoPixelBuffer = CMSampleBufferGetImageBuffer(sampleBuffer) {
self.processSampleBuffer?(sampleBuffer, videoPixelBuffer, connection)
} else if sampleBuffer.type == kCMMediaType_Audio {
self.processAudioBuffer?(sampleBuffer)
}
if let masterOutput = self.masterOutput {
masterOutput.processVideoRecording(sampleBuffer, fromAdditionalOutput: true)
} else {
self.processVideoRecording(sampleBuffer, fromAdditionalOutput: false)
}
if let videoPixelBuffer = CMSampleBufferGetImageBuffer(sampleBuffer) {
self.processSampleBuffer?(sampleBuffer, videoPixelBuffer, connection)
} else if sampleBuffer.type == kCMMediaType_Audio {
self.processAudioBuffer?(sampleBuffer)
}
}
func captureOutput(_ output: AVCaptureOutput, didDrop sampleBuffer: CMSampleBuffer, from connection: AVCaptureConnection) {
if #available(iOS 13.0, *) {
Logger.shared.log("VideoRecorder", "Dropped sample buffer \(sampleBuffer.attachments)")
Logger.shared.log("Camera", "Dropped sample buffer \(sampleBuffer.attachments)")
}
}
}

1
submodules/Camera/Sources/PhotoCaptureContext.swift
View file

@ -56,6 +56,7 @@ final class PhotoCaptureContext: NSObject, AVCapturePhotoCaptureDelegate {
} else {
guard let photoPixelBuffer = photo.pixelBuffer else {
print("Error occurred while capturing photo: Missing pixel buffer (\(String(describing: error)))")
self.pipe.putNext(.failed)
return
}

22
submodules/Camera/Sources/VideoRecorder.swift
View file

@ -204,9 +204,7 @@ private final class VideoRecorderImpl {
let maxDate = Date(timeIntervalSinceNow: 0.05)
RunLoop.current.run(until: maxDate)
}
}
if let videoInput = self.videoInput {
let time = CACurrentMediaTime()
// if let previousPresentationTime = self.previousPresentationTime, let previousAppendTime = self.previousAppendTime {
// print("appending \(presentationTime.seconds) (\(presentationTime.seconds - previousPresentationTime) ) on \(time) (\(time - previousAppendTime)")
@ -234,7 +232,9 @@ private final class VideoRecorderImpl {
} else if self.orientation == .portraitUpsideDown {
orientation = .left
}
self.transitionImage = UIImage(cgImage: cgImage, scale: 1.0, orientation: orientation)
Queue.mainQueue().async {
self.transitionImage = UIImage(cgImage: cgImage, scale: 1.0, orientation: orientation)
}
} else {
self.savedTransitionImage = false
}
@ -366,7 +366,7 @@ private final class VideoRecorderImpl {
private func maybeFinish() {
dispatchPrecondition(condition: .onQueue(self.queue))
guard self.hasAllVideoBuffers && self.hasAllVideoBuffers && !self.stopped else {
guard self.hasAllVideoBuffers && (!self.configuration.hasAudio || self.hasAllAudioBuffers) && !self.stopped else {
return
}
let _ = self._stopped.modify { _ in return true }
@ -377,21 +377,21 @@ private final class VideoRecorderImpl {
dispatchPrecondition(condition: .onQueue(self.queue))
let completion = self.completion
if self.recordingStopSampleTime == .invalid {
DispatchQueue.main.async {
Queue.mainQueue().async {
completion(false, nil, nil)
}
return
}
if let _ = self.error.with({ $0 }) {
DispatchQueue.main.async {
Queue.mainQueue().async {
completion(false, nil, nil)
}
return
}
if !self.tryAppendingPendingAudioBuffers() {
DispatchQueue.main.async {
Queue.mainQueue().async {
completion(false, nil, nil)
}
return
@ -400,21 +400,21 @@ private final class VideoRecorderImpl {
if self.assetWriter.status == .writing {
self.assetWriter.finishWriting {
if let _ = self.assetWriter.error {
DispatchQueue.main.async {
Queue.mainQueue().async {
completion(false, nil, nil)
}
} else {
DispatchQueue.main.async {
Queue.mainQueue().async {
completion(true, self.transitionImage, self.positionChangeTimestamps)
}
}
}
} else if let _ = self.assetWriter.error {
DispatchQueue.main.async {
Queue.mainQueue().async {
completion(false, nil, nil)
}
} else {
DispatchQueue.main.async {
Queue.mainQueue().async {
completion(false, nil, nil)
}
}

22
submodules/ChatListUI/Sources/ChatListController.swift
View file

@ -7389,3 +7389,25 @@ private final class AdsInfoContextReferenceContentSource: ContextReferenceConten
return ContextControllerReferenceViewInfo(referenceView: self.sourceView, contentAreaInScreenSpace: UIScreen.main.bounds.inset(by: self.insets), insets: self.contentInsets)
}
}
public struct ChatListNavigationTarget {
public let chatListController: ChatListControllerImpl
public let popToController: ViewController?
}
public func resolveChatListNavigationTarget(navigationController: NavigationController, excluding excludedController: ViewController? = nil) -> ChatListNavigationTarget? {
for case let controller as ViewController in navigationController.viewControllers.reversed() {
if let excludedController, controller === excludedController {
continue
}
if let chatListController = controller as? ChatListControllerImpl, !chatListController.previewing {
return ChatListNavigationTarget(chatListController: chatListController, popToController: controller)
}
}
if let controller = navigationController.viewControllers.first as? TabBarController, let chatListController = controller.currentController as? ChatListControllerImpl {
return ChatListNavigationTarget(chatListController: chatListController, popToController: nil)
}
return nil
}

20
submodules/ChatListUI/Sources/Node/ChatListItem.swift
View file

@ -2578,6 +2578,7 @@ public class ChatListItemNode: ItemListRevealOptionsItemNode {
case poll
case todo
case game
case voiceMessage
}
var messageTypeIcon: MessageTypeIcon?
var ignoreForwardedIcon = false
@ -2588,6 +2589,10 @@ public class ChatListItemNode: ItemListRevealOptionsItemNode {
if case .user = itemPeer.chatMainPeer {
isUser = true
}
var isGuestChatAuthor = false
if case let .user(user) = messages.last?.author, let botInfo = user.botInfo, botInfo.flags.contains(.isGuestChat) {
isGuestChatAuthor = true
}
var peerText: String?
if case .savedMessagesChats = item.chatListLocation {
@ -2605,14 +2610,14 @@ public class ChatListItemNode: ItemListRevealOptionsItemNode {
if let message = messages.last, let forwardInfo = message.forwardInfo, let author = forwardInfo.author {
peerText = EnginePeer(author).compactDisplayTitle
}
} else if !isUser {
} else if !isUser || isGuestChatAuthor {
if case let .channel(peer) = peer, case .broadcast = peer.info {
} else if !displayAsMessage {
if let forwardInfo = message.forwardInfo, forwardInfo.flags.contains(.isImported), let authorSignature = forwardInfo.authorSignature {
peerText = authorSignature
} else {
peerText = author.id == account.peerId ? item.presentationData.strings.DialogList_You : EnginePeer(author).displayTitle(strings: item.presentationData.strings, displayOrder: item.presentationData.nameDisplayOrder)
authorIsCurrentChat = author.id == peer.id
authorIsCurrentChat = !isGuestChatAuthor && author.id == peer.id
}
}
}
@ -2895,7 +2900,11 @@ public class ChatListItemNode: ItemListRevealOptionsItemNode {
messageTypeIcon = .story
} else {
for media in message.media {
if let _ = media as? TelegramMediaPoll {
if let file = media as? TelegramMediaFile {
if file.isVoice {
messageTypeIcon = .voiceMessage
}
} else if let _ = media as? TelegramMediaPoll {
messageTypeIcon = .poll
} else if let _ = media as? TelegramMediaTodo {
messageTypeIcon = .todo
@ -3106,6 +3115,9 @@ public class ChatListItemNode: ItemListRevealOptionsItemNode {
case .game:
currentMessageTypeIcon = PresentationResourcesChatList.gameIcon(item.presentationData.theme)
currentMessageTypeIconOffset.y = -1.0
case .voiceMessage:
currentMessageTypeIcon = PresentationResourcesChatList.voiceMessageIcon(item.presentationData.theme)
currentMessageTypeIconOffset.y = -1.0
default:
break
}
@ -3115,7 +3127,7 @@ public class ChatListItemNode: ItemListRevealOptionsItemNode {
if !contentImageSpecs.isEmpty {
textLeftCutout += forwardedIconSpacing
} else {
textLeftCutout += contentImageTrailingSpace
textLeftCutout += contentImageTrailingSpace - 1.0
}
}

19
submodules/ChatPresentationInterfaceState/Sources/ChatPresentationInterfaceState.swift
View file

@ -1591,3 +1591,22 @@ public func canSendMessagesToChat(_ state: ChatPresentationInterfaceState) -> Bo
return false
}
}
public func canSendReactionsToChat(_ state: ChatPresentationInterfaceState) -> Bool {
if let peer = state.renderedPeer?.peer {
let canBypassRestrictions = canBypassRestrictions(chatPresentationInterfaceState: state)
return canSendReactionsToPeer(EnginePeer(peer), ignoreDefault: canBypassRestrictions)
} else if case .customChatContents = state.chatLocation {
if case let .customChatContents(contents) = state.subject {
if case .hashTagSearch = contents.kind {
return false
} else {
return true
}
} else {
return true
}
} else {
return false
}
}

13
submodules/ChatTextLinkEditUI/Sources/ChatTextLinkEditController.swift
View file

@ -92,5 +92,18 @@ public func chatTextLinkEditController(
dismissImpl = { [weak alertController] in
alertController?.dismiss(completion: nil)
}
if link == nil {
Queue.mainQueue().after(0.1, {
let pasteboard = UIPasteboard.general
if pasteboard.hasURLs {
if inputState.value.string.isEmpty, let url = pasteboard.url?.absoluteString, !url.isEmpty {
let value = NSAttributedString(string: url)
inputState.setValue(value, selectionRange: 0 ..< value.length)
}
}
})
}
return alertController
}

1
submodules/Components/ReactionListContextMenuContent/BUILD
View file

@ -20,6 +20,7 @@ swift_library(
"//submodules/AnimatedAvatarSetNode:AnimatedAvatarSetNode",
"//submodules/ContextUI:ContextUI",
"//submodules/AvatarNode:AvatarNode",
"//submodules/Components/MultilineTextComponent:MultilineTextComponent",
"//submodules/Components/ReactionImageComponent:ReactionImageComponent",
"//submodules/TelegramUI/Components/AnimationCache:AnimationCache",
"//submodules/TelegramUI/Components/MultiAnimationRenderer:MultiAnimationRenderer",

113
submodules/Components/ReactionListContextMenuContent/Sources/ReactionListContextMenuContent.swift
View file

@ -2,6 +2,7 @@ import Foundation
import AsyncDisplayKit
import Display
import ComponentFlow
import MultilineTextComponent
import SwiftSignalKit
import TelegramCore
import AccountContext
@ -373,12 +374,13 @@ public final class ReactionListContextMenuContent: ContextControllerItemsContent
let availableReactions: AvailableReactions?
let animationCache: AnimationCache
let animationRenderer: MultiAnimationRenderer
private let highlightBackgroundView: UIView
let avatarNode: AvatarNode
let titleLabelNode: ImmediateTextNode
let textLabelNode: ImmediateTextNode
let readIconView: UIImageView
var credibilityIconView: ComponentView<Empty>?
private var reactionLayer: InlineStickerItemLayer?
private var iconFrame: CGRect?
private var file: TelegramMediaFile?
@ -419,16 +421,35 @@ public final class ReactionListContextMenuContent: ContextControllerItemsContent
self.readIconView = UIImageView(image: readIconImage)
self.highlightBackgroundView = UIView()
self.highlightBackgroundView.alpha = 0.0
self.highlightBackgroundView.isUserInteractionEnabled = false
super.init()
self.isAccessibilityElement = true
self.view.insertSubview(self.highlightBackgroundView, at: 0)
self.addSubnode(self.avatarNode)
self.addSubnode(self.titleLabelNode)
self.addSubnode(self.textLabelNode)
self.view.addSubview(self.readIconView)
self.addTarget(self, action: #selector(self.pressed), forControlEvents: .touchUpInside)
self.highligthedChanged = { [weak self] highlighted in
guard let self else {
return
}
if highlighted {
self.highlightBackgroundView.layer.removeAnimation(forKey: "opacity")
self.highlightBackgroundView.alpha = 0.1
} else {
let currentAlpha = self.highlightBackgroundView.alpha
self.highlightBackgroundView.alpha = 0.0
self.highlightBackgroundView.layer.animateAlpha(from: currentAlpha, to: 0.0, duration: 0.3)
}
}
let longTapRecognizer = UILongPressGestureRecognizer(target: self, action: #selector(self.longTapGesture(_:)))
longTapRecognizer.isEnabled = false
@ -537,7 +558,12 @@ public final class ReactionListContextMenuContent: ContextControllerItemsContent
let sideInset: CGFloat = 16.0
let reaction: MessageReaction.Reaction? = item.reaction
self.highlightBackgroundView.backgroundColor = presentationData.theme.overallDarkAppearance ? UIColor.white : UIColor.black
self.highlightBackgroundView.setMonochromaticEffect(tintColor: self.highlightBackgroundView.backgroundColor)
self.highlightBackgroundView.frame = CGRect(origin: CGPoint(x: 10.0, y: 5.0), size: CGSize(width: max(0.0, size.width - 20.0), height: size.height - 10.0))
self.highlightBackgroundView.layer.cornerRadius = self.highlightBackgroundView.frame.height * 0.5
if self.displayReactionIcon, reaction != self.item?.reaction {
if let reaction = reaction {
switch reaction {
@ -810,6 +836,7 @@ public final class ReactionListContextMenuContent: ContextControllerItemsContent
private var hasMore: Bool = false
private let scrollNode: ASScrollNode
private let separatorNode: ASDisplayNode
private var ignoreScrolling: Bool = false
private var animateIn: Bool = false
private var bottomScrollInset: CGFloat = 0.0
@ -826,7 +853,9 @@ public final class ReactionListContextMenuContent: ContextControllerItemsContent
private var placeholderItemImage: UIImage?
private var placeholderLayers: [Int: SimpleLayer] = [:]
private let deleteReactionInfoText: ComponentView<Empty>
init(
context: AccountContext,
displayReadTimestamps: Bool,
@ -858,6 +887,9 @@ public final class ReactionListContextMenuContent: ContextControllerItemsContent
self.state = ItemsState(listState: EngineMessageReactionListContext.State(message: message, readStats: readStats, reaction: reaction), readStats: readStats)
self.scrollNode = ASScrollNode()
self.separatorNode = ASDisplayNode()
self.deleteReactionInfoText = ComponentView<Empty>()
self.scrollNode.canCancelAllTouchesInViews = true
self.scrollNode.view.delaysContentTouches = false
self.scrollNode.view.showsVerticalScrollIndicator = false
@ -871,6 +903,10 @@ public final class ReactionListContextMenuContent: ContextControllerItemsContent
self.addSubnode(self.scrollNode)
self.scrollNode.view.delegate = self.wrappedScrollViewDelegate
self.separatorNode.isHidden = true
self.separatorNode.isUserInteractionEnabled = false
self.scrollNode.addSubnode(self.separatorNode)
self.clipsToBounds = true
self.stateDisposable = (self.listContext.state
@ -965,7 +1001,7 @@ public final class ReactionListContextMenuContent: ContextControllerItemsContent
}
itemNode.update(size: itemFrame.size, presentationData: presentationData, item: item, isLast: self.state.item(at: index + 1) == nil, syncronousLoad: syncronousLoad)
if let deleteReaction = self.deleteReaction, let reaction = item.reaction {
if let deleteReaction = self.deleteReaction, let reaction = item.reaction, item.peer.id != self.context.account.peerId {
let peer = item.peer
itemNode.longTapAction = {
deleteReaction(peer, reaction)
@ -1079,7 +1115,70 @@ public final class ReactionListContextMenuContent: ContextControllerItemsContent
}
self.presentationData = presentationData
let size = CGSize(width: constrainedSize.width, height: topInset + CGFloat(self.state.totalCount) * itemHeight + topInset)
let baseContentHeight = topInset + CGFloat(self.state.totalCount) * itemHeight + topInset
var footerHeight: CGFloat = 0.0
let displayDeleteReactionInfoFooter: Bool
if self.deleteReaction != nil {
displayDeleteReactionInfoFooter = self.state.mergedItems.contains(where: { item in
return item.reaction != nil && item.peer.id != self.context.account.peerId
})
} else {
displayDeleteReactionInfoFooter = false
}
if displayDeleteReactionInfoFooter {
let separatorHeight: CGFloat = 20.0
let horizontalInset: CGFloat = 18.0
let textTopInset: CGFloat = 5.0
let textBottomInset: CGFloat = 18.0
let textFont = Font.regular(floor(presentationData.listsFontSize.baseDisplaySize * 13.0 / 17.0))
self.separatorNode.isHidden = false
self.separatorNode.backgroundColor = presentationData.theme.contextMenu.itemSeparatorColor
var animateIn = false
var footerTransition = transition
if self.deleteReactionInfoText.view?.superview == nil, footerTransition.isAnimated {
footerTransition = .immediate
animateIn = true
}
footerTransition.updateFrame(node: self.separatorNode, frame: CGRect(
origin: CGPoint(x: horizontalInset, y: baseContentHeight + floorToScreenPixels((separatorHeight - UIScreenPixel) * 0.5)),
size: CGSize(width: max(0.0, constrainedSize.width - horizontalInset * 2.0), height: 1.0)
))
let textSize = self.deleteReactionInfoText.update(
transition: ComponentTransition(footerTransition),
component: AnyComponent(MultilineTextComponent(
text: .plain(NSAttributedString(
string: presentationData.strings.Chat_DeleteReactionInfo,
font: textFont,
textColor: presentationData.theme.contextMenu.primaryColor
)),
maximumNumberOfLines: 0
)),
environment: {},
containerSize: CGSize(width: max(0.0, constrainedSize.width - horizontalInset * 2.0), height: .greatestFiniteMagnitude)
)
if let textView = self.deleteReactionInfoText.view {
if textView.superview == nil {
self.scrollNode.view.addSubview(textView)
textView.isUserInteractionEnabled = false
}
footerTransition.updateFrame(view: textView, frame: CGRect(origin: CGPoint(x: horizontalInset, y: baseContentHeight + separatorHeight + textTopInset), size: textSize))
if animateIn {
self.separatorNode.layer.animateAlpha(from: 0.0, to: 1.0, duration: 0.25)
textView.layer.animateAlpha(from: 0.0, to: 1.0, duration: 0.25)
}
}
footerHeight = separatorHeight + textTopInset + textSize.height + textBottomInset
} else {
self.separatorNode.isHidden = true
self.deleteReactionInfoText.view?.removeFromSuperview()
}
let size = CGSize(width: constrainedSize.width, height: baseContentHeight + footerHeight)
let containerSize = CGSize(width: size.width, height: min(constrainedSize.height, size.height))
self.currentSize = containerSize

54
submodules/DebugSettingsUI/Sources/DebugController.swift
View file

@ -98,6 +98,7 @@ private enum DebugControllerEntry: ItemListNodeEntry {
case fakeGlass(Bool)
case forceClearGlass(Bool)
case debugRipple(Bool)
case debugRichText(Bool)
case browserExperiment(Bool)
case allForumsHaveTabs(Bool)
case enableReactionOverrides(Bool)
@ -137,7 +138,7 @@ private enum DebugControllerEntry: ItemListNodeEntry {
return DebugControllerSection.web.rawValue
case .keepChatNavigationStack, .skipReadHistory, .alwaysDisplayTyping, .debugRatingLayout, .crashOnSlowQueries, .crashOnMemoryPressure:
return DebugControllerSection.experiments.rawValue
case .clearTips, .resetNotifications, .crash, .fillLocalSavedMessageCache, .resetDatabase, .resetDatabaseAndCache, .resetHoles, .resetTagHoles, .reindexUnread, .resetCacheIndex, .reindexCache, .resetBiometricsData, .optimizeDatabase, .photoPreview, .knockoutWallpaper, .compressedEmojiCache, .storiesJpegExperiment, .checkSerializedData, .enableQuickReactionSwitch, .experimentalCompatibility, .enableDebugDataDisplay, .fakeGlass, .forceClearGlass, .debugRipple, .browserExperiment, .allForumsHaveTabs, .enableReactionOverrides, .restorePurchases, .disableReloginTokens, .liveStreamV2, .experimentalCallMute, .playerV2, .devRequests, .enableUpdates, .pwa, .enableLocalTranslation:
case .clearTips, .resetNotifications, .crash, .fillLocalSavedMessageCache, .resetDatabase, .resetDatabaseAndCache, .resetHoles, .resetTagHoles, .reindexUnread, .resetCacheIndex, .reindexCache, .resetBiometricsData, .optimizeDatabase, .photoPreview, .knockoutWallpaper, .compressedEmojiCache, .storiesJpegExperiment, .checkSerializedData, .enableQuickReactionSwitch, .experimentalCompatibility, .enableDebugDataDisplay, .fakeGlass, .forceClearGlass, .debugRipple, .debugRichText, .browserExperiment, .allForumsHaveTabs, .enableReactionOverrides, .restorePurchases, .disableReloginTokens, .liveStreamV2, .experimentalCallMute, .playerV2, .devRequests, .enableUpdates, .pwa, .enableLocalTranslation:
return DebugControllerSection.experiments.rawValue
case .logTranslationRecognition, .resetTranslationStates:
return DebugControllerSection.translation.rawValue
@ -234,44 +235,46 @@ private enum DebugControllerEntry: ItemListNodeEntry {
return 40
case .debugRipple:
return 41
case .browserExperiment:
case .debugRichText:
return 42
case .allForumsHaveTabs:
case .browserExperiment:
return 43
case .enableReactionOverrides:
case .allForumsHaveTabs:
return 44
case .restorePurchases:
case .enableReactionOverrides:
return 45
case .logTranslationRecognition:
case .restorePurchases:
return 46
case .resetTranslationStates:
case .logTranslationRecognition:
return 47
case .compressedEmojiCache:
case .resetTranslationStates:
return 48
case .storiesJpegExperiment:
case .compressedEmojiCache:
return 49
case .disableReloginTokens:
case .storiesJpegExperiment:
return 50
case .checkSerializedData:
case .disableReloginTokens:
return 51
case .enableQuickReactionSwitch:
case .checkSerializedData:
return 52
case .liveStreamV2:
case .enableQuickReactionSwitch:
return 53
case .experimentalCallMute:
case .liveStreamV2:
return 54
case .playerV2:
case .experimentalCallMute:
return 55
case .devRequests:
case .playerV2:
return 56
case .pwa:
case .devRequests:
return 57
case .enableLocalTranslation:
case .pwa:
return 58
case .enableUpdates:
case .enableLocalTranslation:
return 59
case .enableUpdates:
return 60
case let .preferredVideoCodec(index, _, _, _):
return 60 + index
return 61 + index
case .disableVideoAspectScaling:
return 100
case .enableNetworkFramework:
@ -1305,6 +1308,16 @@ private enum DebugControllerEntry: ItemListNodeEntry {
})
}).start()
})
case let .debugRichText(value):
return ItemListSwitchItem(presentationData: presentationData, systemStyle: .glass, title: "Debug Text", value: value, sectionId: self.section, style: .blocks, updated: { value in
let _ = arguments.sharedContext.accountManager.transaction ({ transaction in
transaction.updateSharedData(ApplicationSpecificSharedDataKeys.experimentalUISettings, { settings in
var settings = settings?.get(ExperimentalUISettings.self) ?? ExperimentalUISettings.defaultSettings
settings.debugRichText = value
return PreferencesEntry(settings)
})
}).start()
})
case let .browserExperiment(value):
return ItemListSwitchItem(presentationData: presentationData, systemStyle: .glass, title: "Inline UI", value: value, sectionId: self.section, style: .blocks, updated: { value in
let _ = arguments.sharedContext.accountManager.transaction ({ transaction in
@ -1583,6 +1596,7 @@ private func debugControllerEntries(context: AccountContext?, sharedContext: Sha
entries.append(.fakeGlass(experimentalSettings.fakeGlass))
entries.append(.forceClearGlass(experimentalSettings.forceClearGlass))
entries.append(.debugRipple(experimentalSettings.debugRipple))
entries.append(.debugRichText(experimentalSettings.debugRichText))
#if DEBUG
entries.append(.browserExperiment(experimentalSettings.browserExperiment))
#else

34
submodules/Display/Source/ContainedViewLayoutTransition.swift
View file

@ -408,7 +408,7 @@ public extension ContainedViewLayoutTransition {
}
}
func updateBounds(layer: CALayer, bounds: CGRect, force: Bool = false, completion: ((Bool) -> Void)? = nil) {
func updateBounds(layer: CALayer, bounds: CGRect, beginWithCurrentState: Bool = false, force: Bool = false, completion: ((Bool) -> Void)? = nil) {
if layer.bounds.equalTo(bounds) && !force {
completion?(true)
} else {
@ -420,7 +420,12 @@ public extension ContainedViewLayoutTransition {
completion(true)
}
case let .animated(duration, curve):
let previousBounds = layer.bounds
let previousBounds: CGRect
if beginWithCurrentState, layer.animation(forKey: "bounds") != nil, let presentation = layer.presentation() {
previousBounds = presentation.bounds
} else {
previousBounds = layer.bounds
}
layer.bounds = bounds
layer.animateBounds(from: previousBounds, to: bounds, duration: duration, timingFunction: curve.timingFunction, mediaTimingFunction: curve.mediaTimingFunction, force: force, completion: { result in
if let completion = completion {
@ -459,7 +464,7 @@ public extension ContainedViewLayoutTransition {
}
}
func updatePosition(layer: CALayer, position: CGPoint, force: Bool = false, completion: ((Bool) -> Void)? = nil) {
func updatePosition(layer: CALayer, position: CGPoint, force: Bool = false, beginFromCurrentState: Bool = false, completion: ((Bool) -> Void)? = nil) {
if layer.position.equalTo(position) && !force {
completion?(true)
} else {
@ -471,7 +476,22 @@ public extension ContainedViewLayoutTransition {
completion(true)
}
case let .animated(duration, curve):
let previousPosition = layer.position
let previousPosition: CGPoint
if beginFromCurrentState, let animationKeys = layer.animationKeys(), animationKeys.contains(where: { key in
guard let animation = layer.animation(forKey: key) as? CAPropertyAnimation else {
return false
}
if animation.keyPath == "position" {
return true
} else {
return false
}
}) {
previousPosition = layer.presentation()?.position ?? layer.position
} else {
previousPosition = layer.position
}
layer.position = position
layer.animatePosition(from: previousPosition, to: position, duration: duration, timingFunction: curve.timingFunction, mediaTimingFunction: curve.mediaTimingFunction, completion: { result in
if let completion = completion {
@ -2767,7 +2787,7 @@ public final class ControlledTransition {
}
public func updatePosition(layer: CALayer, position: CGPoint, completion: ((Bool) -> Void)?) {
self.transition.updatePosition(layer: layer, position: position, completion: completion)
self.transition.updatePosition(layer: layer, position: position, beginFromCurrentState: true, completion: completion)
}
public func updateTransform(layer: CALayer, transform: CATransform3D, completion: ((Bool) -> Void)?) {
@ -2787,11 +2807,11 @@ public final class ControlledTransition {
}
public func updateBounds(layer: CALayer, bounds: CGRect, completion: ((Bool) -> Void)?) {
self.transition.updateBounds(layer: layer, bounds: bounds, completion: completion)
self.transition.updateBounds(layer: layer, bounds: bounds, beginWithCurrentState: true, completion: completion)
}
public func updateFrame(layer: CALayer, frame: CGRect, completion: ((Bool) -> Void)?) {
self.transition.updateFrame(layer: layer, frame: frame, completion: completion)
self.transition.updateFrame(layer: layer, frame: frame, beginWithCurrentState: true, completion: completion)
}
public func updateCornerRadius(layer: CALayer, cornerRadius: CGFloat, completion: ((Bool) -> Void)?) {

64
submodules/Display/Source/ListView.swift
View file

@ -1101,6 +1101,8 @@ open class ListViewImpl: ASDisplayNode, ListView, ASScrollViewDelegate, ASGestur
}
guard lowestPinnedIndex != Int.max else { return 0.0 }
let visibleArea = self.visibleSize.height - self.insets.top - self.insets.bottom
var totalAboveAndPinned: CGFloat = 0.0
var sawIndexZero = false
for itemNode in self.itemNodes {
@ -1108,16 +1110,25 @@ open class ListViewImpl: ASDisplayNode, ListView, ASScrollViewDelegate, ASGestur
if index == 0 {
sawIndexZero = true
}
if index <= lowestPinnedIndex {
if index < lowestPinnedIndex {
totalAboveAndPinned += itemNode.apparentBounds.height
} else if index == lowestPinnedIndex {
let pinnedHeight = itemNode.apparentBounds.height
totalAboveAndPinned += pinnedHeight - self.pinToEdgeBottomExtension(forPinnedHeight: pinnedHeight)
}
}
guard sawIndexZero else { return 0.0 }
let visibleArea = self.visibleSize.height - self.insets.top - self.insets.bottom
return max(0.0, visibleArea - totalAboveAndPinned)
}
private func pinToEdgeBottomExtension(forPinnedHeight pinnedHeight: CGFloat) -> CGFloat {
let visibleArea = self.visibleSize.height - self.insets.top - self.insets.bottom
let halfArea = visibleArea * 0.5
guard halfArea > 0.0 else { return 0.0 }
return max(0.0, pinnedHeight - halfArea)
}
private func areAllItemsOnScreen() -> Bool {
if self.itemNodes.count == 0 {
return true
@ -1856,7 +1867,7 @@ open class ListViewImpl: ASDisplayNode, ListView, ASScrollViewDelegate, ASGestur
})
}
public func transaction(deleteIndices: [ListViewDeleteItem], insertIndicesAndItems: [ListViewInsertItem], updateIndicesAndItems: [ListViewUpdateItem], options: ListViewDeleteAndInsertOptions, scrollToItem: ListViewScrollToItem? = nil, additionalScrollDistance: CGFloat = 0.0, updateSizeAndInsets: ListViewUpdateSizeAndInsets? = nil, stationaryItemRange: (Int, Int)? = nil, updateOpaqueState: Any?, completion: @escaping (ListViewDisplayedItemRange) -> Void = { _ in }) {
public func transaction(deleteIndices: [ListViewDeleteItem], insertIndicesAndItems: [ListViewInsertItem], updateIndicesAndItems: [ListViewUpdateItem], options: ListViewDeleteAndInsertOptions, scrollToItem: ListViewScrollToItem? = nil, additionalScrollDistance: CGFloat = 0.0, updateSizeAndInsets: ListViewUpdateSizeAndInsets? = nil, stationaryItemRange: (Int, Int)? = nil, customAnimationTransition: ControlledTransition? = nil, updateOpaqueState: Any?, completion: @escaping (ListViewDisplayedItemRange) -> Void = { _ in }) {
if deleteIndices.isEmpty && insertIndicesAndItems.isEmpty && updateIndicesAndItems.isEmpty && scrollToItem == nil && updateSizeAndInsets == nil && additionalScrollDistance.isZero {
if let updateOpaqueState = updateOpaqueState {
self.opaqueTransactionState = updateOpaqueState
@ -1868,7 +1879,7 @@ open class ListViewImpl: ASDisplayNode, ListView, ASScrollViewDelegate, ASGestur
self.transactionQueue.addTransaction({ [weak self] transactionCompletion in
if let strongSelf = self {
strongSelf.transactionOffset = 0.0
strongSelf.deleteAndInsertItemsTransaction(deleteIndices: deleteIndices, insertIndicesAndItems: insertIndicesAndItems, updateIndicesAndItems: updateIndicesAndItems, options: options, scrollToItem: scrollToItem, additionalScrollDistance: additionalScrollDistance, updateSizeAndInsets: updateSizeAndInsets, stationaryItemRange: stationaryItemRange, updateOpaqueState: updateOpaqueState, customAnimationTransition: updateSizeAndInsets?.customAnimationTransition, completion: { [weak strongSelf] in
strongSelf.deleteAndInsertItemsTransaction(deleteIndices: deleteIndices, insertIndicesAndItems: insertIndicesAndItems, updateIndicesAndItems: updateIndicesAndItems, options: options, scrollToItem: scrollToItem, additionalScrollDistance: additionalScrollDistance, updateSizeAndInsets: updateSizeAndInsets, stationaryItemRange: stationaryItemRange, updateOpaqueState: updateOpaqueState, customAnimationTransition: customAnimationTransition ?? updateSizeAndInsets?.customAnimationTransition, completion: { [weak strongSelf] in
completion(strongSelf?.immediateDisplayedItemRange() ?? ListViewDisplayedItemRange(loadedRange: nil, visibleRange: nil))
transactionCompletion()
@ -2671,6 +2682,27 @@ open class ListViewImpl: ASDisplayNode, ListView, ASScrollViewDelegate, ASGestur
return value
}
public func isStrictlyScrolledToPinToEdgeItem() -> Bool {
guard let targetIndex = self.items.firstIndex(where: { $0.pinToEdgeWithInset }) else {
return false
}
let pinToEdgeTopInset = self.calculatePinToEdgeTopInset()
if pinToEdgeTopInset <= 0.0 {
return false
}
for itemNode in self.itemNodes {
if itemNode.index == targetIndex {
let extensionOffset = self.pinToEdgeBottomExtension(forPinnedHeight: itemNode.apparentBounds.height)
guard pinToEdgeTopInset > 0.0 || extensionOffset > 0.0 else {
return false
}
let expectedMaxY = (self.visibleSize.height - self.insets.bottom + extensionOffset) + itemNode.scrollPositioningInsets.bottom
return abs(itemNode.apparentFrame.maxY - expectedMaxY) < 0.5
}
}
return false
}
private func replayOperations(animated: Bool, animateAlpha: Bool, animateCrossfade: Bool, animateFullTransition: Bool, customAnimationTransition: ControlledTransition?, synchronous: Bool, synchronousLoads: Bool, animateTopItemVerticalOrigin: Bool, operations: [ListViewStateOperation], requestItemInsertionAnimationsIndices: Set<Int>, scrollToItem originalScrollToItem: ListViewScrollToItem?, additionalScrollDistance: CGFloat, updateSizeAndInsets: ListViewUpdateSizeAndInsets?, stationaryItemIndex: Int?, updateOpaqueState: Any?, forceInvertOffsetDirection: Bool = false, completion: () -> Void) {
var scrollToItem: ListViewScrollToItem?
var isExperimentalSnapToScrollToItem = false
@ -3092,23 +3124,25 @@ open class ListViewImpl: ASDisplayNode, ListView, ASScrollViewDelegate, ASGestur
let insets = self.insets// updateSizeAndInsets?.insets ?? self.insets
var isPinToEdgeTarget = false
if self.calculatePinToEdgeTopInset() > 0.0,
index >= 0, index < self.items.count,
self.items[index].pinToEdgeWithInset {
isPinToEdgeTarget = true
for otherNode in self.itemNodes {
guard let otherIndex = otherNode.index else { continue }
guard otherIndex >= 0, otherIndex < self.items.count else { continue }
if otherIndex < index, self.items[otherIndex].pinToEdgeWithInset {
isPinToEdgeTarget = false
break
if index >= 0, index < self.items.count, self.items[index].pinToEdgeWithInset {
let pinExtension = self.pinToEdgeBottomExtension(forPinnedHeight: itemNode.apparentBounds.height)
if self.calculatePinToEdgeTopInset() > 0.0 || pinExtension > 0.0 {
isPinToEdgeTarget = true
for otherNode in self.itemNodes {
guard let otherIndex = otherNode.index else { continue }
guard otherIndex >= 0, otherIndex < self.items.count else { continue }
if otherIndex < index, self.items[otherIndex].pinToEdgeWithInset {
isPinToEdgeTarget = false
break
}
}
}
}
var offset: CGFloat
if isPinToEdgeTarget {
offset = (self.visibleSize.height - insets.bottom) - itemNode.apparentFrame.maxY + itemNode.scrollPositioningInsets.bottom
let extensionOffset = self.pinToEdgeBottomExtension(forPinnedHeight: itemNode.apparentBounds.height)
offset = (self.visibleSize.height - insets.bottom + extensionOffset) - itemNode.apparentFrame.maxY + itemNode.scrollPositioningInsets.bottom
} else {
switch scrollToItem.position {
case let .bottom(additionalOffset):

3
submodules/Display/Source/ListViewProtocol.swift
View file

@ -67,6 +67,7 @@ public protocol ListView: ASDisplayNode {
additionalScrollDistance: CGFloat,
updateSizeAndInsets: ListViewUpdateSizeAndInsets?,
stationaryItemRange: (Int, Int)?,
customAnimationTransition: ControlledTransition?,
updateOpaqueState: Any?,
completion: @escaping (ListViewDisplayedItemRange) -> Void
)
@ -102,6 +103,7 @@ public extension ListView {
additionalScrollDistance: CGFloat = 0.0,
updateSizeAndInsets: ListViewUpdateSizeAndInsets? = nil,
stationaryItemRange: (Int, Int)? = nil,
customAnimationTransition: ControlledTransition? = nil,
updateOpaqueState: Any?,
completion: @escaping (ListViewDisplayedItemRange) -> Void = { _ in }
) {
@ -114,6 +116,7 @@ public extension ListView {
additionalScrollDistance: additionalScrollDistance,
updateSizeAndInsets: updateSizeAndInsets,
stationaryItemRange: stationaryItemRange,
customAnimationTransition: customAnimationTransition,
updateOpaqueState: updateOpaqueState,
completion: completion
)

15
submodules/FeaturedStickersScreen/Sources/FeaturedStickersScreen.swift
View file

@ -863,6 +863,8 @@ public final class FeaturedStickersScreen: ViewController {
fileprivate var searchNavigationNode: SearchNavigationContentNode?
private var eventsDisposable: Disposable?
public init(context: AccountContext, highlightedPackId: ItemCollectionId?, forceTheme: PresentationTheme? = nil, stickerActionTitle: String? = nil, sendSticker: ((FileMediaReference, UIView?, CGRect?) -> Bool)? = nil) {
self.context = context
self.highlightedPackId = highlightedPackId
@ -906,6 +908,18 @@ public final class FeaturedStickersScreen: ViewController {
}
}
})
self.eventsDisposable = (context.account.stateManager.installedStickerPacksArchivedEvents
|> deliverOnMainQueue).startStrict(next: { [weak self] count in
guard let self else {
return
}
if count == 0 {
return
}
let presentationData = self.presentationData
self.push(textAlertController(context: self.context, updatedPresentationData: nil, title: nil, text: presentationData.strings.ArchivedPacksAlert_Title, actions: [TextAlertAction(type: .defaultAction, title: presentationData.strings.Common_OK, action: {})]))
})
}
required init(coder aDecoder: NSCoder) {
@ -914,6 +928,7 @@ public final class FeaturedStickersScreen: ViewController {
deinit {
self.presentationDataDisposable?.dispose()
self.eventsDisposable?.dispose()
}
private func updatePresentationData() {

25
submodules/GalleryData/Sources/GalleryData.swift
View file

@ -174,15 +174,26 @@ public func chatMessageGalleryControllerData(
}
}
if let instantPage = content.instantPage, let galleryMedia = galleryMedia {
switch instantPageType(of: content) {
case .album:
let medias = instantPageGalleryMedia(webpageId: webpage.webpageId, page: instantPage, galleryMedia: galleryMedia)
if medias.count > 1 {
if let instantPage = content.instantPage {
if case let .instantPageMedia(tappedMediaId) = mediaSubject {
let parsedPage = instantPage._parse()
if let tappedMedia = parsedPage.media[tappedMediaId] {
let medias = instantPageGalleryMedia(webpageId: webpage.webpageId, page: instantPage, galleryMedia: tappedMedia)
if !medias.isEmpty {
instantPageMedia = (webpage, medias)
galleryMedia = tappedMedia
}
default:
break
}
} else if let galleryMedia = galleryMedia {
switch instantPageType(of: content) {
case .album:
let medias = instantPageGalleryMedia(webpageId: webpage.webpageId, page: instantPage, galleryMedia: galleryMedia)
if medias.count > 1 {
instantPageMedia = (webpage, medias)
}
default:
break
}
}
}
} else if let mapMedia = media as? TelegramMediaMap {

18
submodules/InAppPurchaseManager/Sources/InAppPurchaseManager.swift
View file

@ -28,6 +28,7 @@ private let productIdentifiers = [
"org.telegram.telegramPremium.twelveMonths.code_x10",
"org.telegram.telegramPremium.oneWeek.auth",
"org.telegram.telegramPremium.threeDays.auth",
"org.telegram.telegramStars.topup.x15",
"org.telegram.telegramStars.topup.x25",
@ -662,6 +663,7 @@ private final class PendingInAppPurchaseState: Codable {
case restore
case phoneNumber
case phoneCodeHash
case premiumDays
}
enum PurposeType: Int32 {
@ -686,7 +688,7 @@ private final class PendingInAppPurchaseState: Codable {
case stars(count: Int64, peerId: EnginePeer.Id?)
case starsGift(peerId: EnginePeer.Id, count: Int64)
case starsGiveaway(stars: Int64, boostPeer: EnginePeer.Id, additionalPeerIds: [EnginePeer.Id], countries: [String], onlyNewSubscribers: Bool, showWinners: Bool, prizeDescription: String?, randomId: Int64, untilDate: Int32, users: Int32)
case authCode(restore: Bool, phoneNumber: String, phoneCodeHash: String)
case authCode(restore: Bool, phoneNumber: String, phoneCodeHash: String, premiumDays: Int32)
public init(from decoder: Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
@ -748,7 +750,8 @@ private final class PendingInAppPurchaseState: Codable {
self = .authCode(
restore: try container.decode(Bool.self, forKey: .restore),
phoneNumber: try container.decode(String.self, forKey: .phoneNumber),
phoneCodeHash: try container.decode(String.self, forKey: .phoneCodeHash)
phoneCodeHash: try container.decode(String.self, forKey: .phoneCodeHash),
premiumDays: try container.decode(Int32.self, forKey: .premiumDays),
)
default:
throw DecodingError.generic
@ -804,11 +807,12 @@ private final class PendingInAppPurchaseState: Codable {
try container.encode(randomId, forKey: .randomId)
try container.encode(untilDate, forKey: .untilDate)
try container.encode(users, forKey: .users)
case let .authCode(restore, phoneNumber, phoneCodeHash):
case let .authCode(restore, phoneNumber, phoneCodeHash, premiumDays):
try container.encode(PurposeType.authCode.rawValue, forKey: .type)
try container.encode(restore, forKey: .restore)
try container.encode(phoneNumber, forKey: .phoneNumber)
try container.encode(phoneCodeHash, forKey: .phoneCodeHash)
try container.encode(premiumDays, forKey: .premiumDays)
}
}
@ -832,8 +836,8 @@ private final class PendingInAppPurchaseState: Codable {
self = .starsGift(peerId: peerId, count: count)
case let .starsGiveaway(stars, boostPeer, additionalPeerIds, countries, onlyNewSubscribers, showWinners, prizeDescription, randomId, untilDate, _, _, users):
self = .starsGiveaway(stars: stars, boostPeer: boostPeer, additionalPeerIds: additionalPeerIds, countries: countries, onlyNewSubscribers: onlyNewSubscribers, showWinners: showWinners, prizeDescription: prizeDescription, randomId: randomId, untilDate: untilDate, users: users)
case let .authCode(restore, phoneNumber, phoneCodeHash, _, _):
self = .authCode(restore: restore, phoneNumber: phoneNumber, phoneCodeHash: phoneCodeHash)
case let .authCode(restore, phoneNumber, phoneCodeHash, premiumDays, _, _):
self = .authCode(restore: restore, phoneNumber: phoneNumber, phoneCodeHash: phoneCodeHash, premiumDays: premiumDays)
}
}
@ -858,8 +862,8 @@ private final class PendingInAppPurchaseState: Codable {
return .starsGift(peerId: peerId, count: count, currency: currency, amount: amount)
case let .starsGiveaway(stars, boostPeer, additionalPeerIds, countries, onlyNewSubscribers, showWinners, prizeDescription, randomId, untilDate, users):
return .starsGiveaway(stars: stars, boostPeer: boostPeer, additionalPeerIds: additionalPeerIds, countries: countries, onlyNewSubscribers: onlyNewSubscribers, showWinners: showWinners, prizeDescription: prizeDescription, randomId: randomId, untilDate: untilDate, currency: currency, amount: amount, users: users)
case let .authCode(restore, phoneNumber, phoneCodeHash):
return .authCode(restore: restore, phoneNumber: phoneNumber, phoneCodeHash: phoneCodeHash, currency: currency, amount: amount)
case let .authCode(restore, phoneNumber, phoneCodeHash, premiumDays):
return .authCode(restore: restore, phoneNumber: phoneNumber, phoneCodeHash: phoneCodeHash, premiumDays: premiumDays, currency: currency, amount: amount)
}
}
}

4
submodules/InstantPageUI/Sources/InstantPageControllerNode.swift
View file

@ -256,7 +256,7 @@ final class InstantPageControllerNode: ASDisplayNode, ASScrollViewDelegate {
updateLayout = true
animated = true
}
if previousSettings.fontSize != settings.fontSize || previousSettings.forceSerif != settings.forceSerif {
if previousSettings.fontSize != settings.fontSize || previousSettings.lineSpacingFactor != settings.lineSpacingFactor || previousSettings.forceSerif != settings.forceSerif {
animated = false
updateLayout = true
}
@ -475,7 +475,7 @@ final class InstantPageControllerNode: ASDisplayNode, ASScrollViewDelegate {
return
}
let currentLayout = instantPageLayoutForWebPage(webPage, instantPage: instantPage, userLocation: self.sourceLocation.userLocation, boundingWidth: containerLayout.size.width, safeInset: containerLayout.safeInsets.left, strings: self.strings, theme: theme, dateTimeFormat: self.dateTimeFormat, webEmbedHeights: self.currentWebEmbedHeights)
let currentLayout = instantPageLayoutForWebPage(webPage, instantPage: instantPage, userLocation: self.sourceLocation.userLocation, boundingWidth: containerLayout.size.width, sideInset: 17.0, safeInset: containerLayout.safeInsets.left, strings: self.strings, theme: theme, dateTimeFormat: self.dateTimeFormat, webEmbedHeights: self.currentWebEmbedHeights)
let currentLayoutTiles = instantPageTilesFromLayout(currentLayout, boundingWidth: containerLayout.size.width)

51
submodules/InstantPageUI/Sources/InstantPageLayout.swift
View file

@ -165,8 +165,7 @@ private func instantPageFirstTextLineMidY(in items: [InstantPageItem]) -> CGFloa
return nil
}
public func layoutInstantPageBlock(webpage: TelegramMediaWebpage, userLocation: MediaResourceUserLocation, rtl: Bool, block: InstantPageBlock, boundingWidth: CGFloat, horizontalInset: CGFloat, safeInset: CGFloat, isCover: Bool, previousItems: [InstantPageItem], fillToSize: CGSize?, media: [EngineMedia.Id: EngineMedia], mediaIndexCounter: inout Int, embedIndexCounter: inout Int, detailsIndexCounter: inout Int, theme: InstantPageTheme, strings: PresentationStrings, dateTimeFormat: PresentationDateTimeFormat, webEmbedHeights: [Int : CGFloat] = [:], cachedMessageSyntaxHighlight: CachedMessageSyntaxHighlight? = nil, excludeCaptions: Bool) -> InstantPageLayout {
public func layoutInstantPageBlock(webpage: TelegramMediaWebpage, userLocation: MediaResourceUserLocation, rtl: Bool, block: InstantPageBlock, boundingWidth: CGFloat, horizontalInset: CGFloat, safeInset: CGFloat, isCover: Bool, previousItems: [InstantPageItem], fillToSize: CGSize?, media: [EngineMedia.Id: EngineMedia], mediaIndexCounter: inout Int, embedIndexCounter: inout Int, detailsIndexCounter: inout Int, theme: InstantPageTheme, strings: PresentationStrings, dateTimeFormat: PresentationDateTimeFormat, webEmbedHeights: [Int : CGFloat] = [:], cachedMessageSyntaxHighlight: CachedMessageSyntaxHighlight? = nil, excludeCaptions: Bool, isLast: Bool) -> InstantPageLayout {
let layoutCaption: (InstantPageCaption, CGSize) -> ([InstantPageItem], CGSize) = { caption, contentSize in
var items: [InstantPageItem] = []
var offset = contentSize.height
@ -218,7 +217,7 @@ public func layoutInstantPageBlock(webpage: TelegramMediaWebpage, userLocation:
switch block {
case let .cover(block):
return layoutInstantPageBlock(webpage: webpage, userLocation: userLocation, rtl: rtl, block: block, boundingWidth: boundingWidth, horizontalInset: horizontalInset, safeInset: safeInset, isCover: true, previousItems:previousItems, fillToSize: fillToSize, media: media, mediaIndexCounter: &mediaIndexCounter, embedIndexCounter: &embedIndexCounter, detailsIndexCounter: &detailsIndexCounter, theme: theme, strings: strings, dateTimeFormat: dateTimeFormat, webEmbedHeights: webEmbedHeights, cachedMessageSyntaxHighlight: cachedMessageSyntaxHighlight, excludeCaptions: false)
return layoutInstantPageBlock(webpage: webpage, userLocation: userLocation, rtl: rtl, block: block, boundingWidth: boundingWidth, horizontalInset: horizontalInset, safeInset: safeInset, isCover: true, previousItems:previousItems, fillToSize: fillToSize, media: media, mediaIndexCounter: &mediaIndexCounter, embedIndexCounter: &embedIndexCounter, detailsIndexCounter: &detailsIndexCounter, theme: theme, strings: strings, dateTimeFormat: dateTimeFormat, webEmbedHeights: webEmbedHeights, cachedMessageSyntaxHighlight: cachedMessageSyntaxHighlight, excludeCaptions: false, isLast: true)
case let .title(text):
let styleStack = InstantPageTextStyleStack()
setupStyleStack(styleStack, theme: theme, category: .header, link: false)
@ -355,9 +354,13 @@ public func layoutInstantPageBlock(webpage: TelegramMediaWebpage, userLocation:
let (_, items, contentSize) = layoutTextItemWithString(attributedStringForRichText(text, styleStack: styleStack), boundingWidth: boundingWidth - horizontalInset * 2.0, offset: CGPoint(x: horizontalInset, y: 0.0), media: media, webpage: webpage)
return InstantPageLayout(origin: CGPoint(), contentSize: contentSize, items: items)
case .divider:
let lineWidth = floor(boundingWidth / 2.0)
let shapeItem = InstantPageShapeItem(frame: CGRect(origin: CGPoint(x: floor((boundingWidth - lineWidth) / 2.0), y: 0.0), size: CGSize(width: lineWidth, height: 1.0)), shapeFrame: CGRect(origin: CGPoint(), size: CGSize(width: lineWidth, height: 1.0)), shape: .rect, color: theme.textCategories.caption.color)
return InstantPageLayout(origin: CGPoint(), contentSize: shapeItem.frame.size, items: [shapeItem])
if isLast {
return InstantPageLayout(origin: CGPoint(), contentSize: CGSize(), items: [])
} else {
let lineWidth = floor(boundingWidth / 2.0)
let shapeItem = InstantPageShapeItem(frame: CGRect(origin: CGPoint(x: floor((boundingWidth - lineWidth) / 2.0), y: 0.0), size: CGSize(width: lineWidth, height: 1.0)), shapeFrame: CGRect(origin: CGPoint(), size: CGSize(width: lineWidth, height: 1.0)), shape: .rect, color: theme.textCategories.caption.color)
return InstantPageLayout(origin: CGPoint(), contentSize: shapeItem.frame.size, items: [shapeItem])
}
case let .list(contentItems, ordered):
var contentSize = CGSize(width: boundingWidth, height: 0.0)
var maxIndexWidth: CGFloat = 0.0
@ -462,8 +465,9 @@ public func layoutInstantPageBlock(webpage: TelegramMediaWebpage, userLocation:
var previousBlock: InstantPageBlock?
var originY: CGFloat = contentSize.height
var firstBlockLineMidY: CGFloat?
for subBlock in blocks {
let subLayout = layoutInstantPageBlock(webpage: webpage, userLocation: userLocation, rtl: rtl, block: subBlock, boundingWidth: boundingWidth - horizontalInset * 2.0 - indexSpacing - maxIndexWidth, horizontalInset: 0.0, safeInset: 0.0, isCover: false, previousItems: listItems, fillToSize: nil, media: media, mediaIndexCounter: &mediaIndexCounter, embedIndexCounter: &embedIndexCounter, detailsIndexCounter: &detailsIndexCounter, theme: theme, strings: strings, dateTimeFormat: dateTimeFormat, webEmbedHeights: webEmbedHeights, cachedMessageSyntaxHighlight: cachedMessageSyntaxHighlight, excludeCaptions: false)
for i in 0 ..< blocks.count {
let subBlock = blocks[i]
let subLayout = layoutInstantPageBlock(webpage: webpage, userLocation: userLocation, rtl: rtl, block: subBlock, boundingWidth: boundingWidth - horizontalInset * 2.0 - indexSpacing - maxIndexWidth, horizontalInset: 0.0, safeInset: 0.0, isCover: false, previousItems: listItems, fillToSize: nil, media: media, mediaIndexCounter: &mediaIndexCounter, embedIndexCounter: &embedIndexCounter, detailsIndexCounter: &detailsIndexCounter, theme: theme, strings: strings, dateTimeFormat: dateTimeFormat, webEmbedHeights: webEmbedHeights, cachedMessageSyntaxHighlight: cachedMessageSyntaxHighlight, excludeCaptions: false, isLast: i == blocks.count - 1)
let spacing: CGFloat = previousBlock != nil && subLayout.contentSize.height > 0.0 ? spacingBetweenBlocks(upper: previousBlock, lower: subBlock) : 0.0
let blockItems = subLayout.flattenedItemsWithOrigin(CGPoint(x: horizontalInset + indexSpacing + maxIndexWidth, y: contentSize.height + spacing))
@ -680,7 +684,7 @@ public func layoutInstantPageBlock(webpage: TelegramMediaWebpage, userLocation:
var i = 0
for subItem in innerItems {
let frame = mosaicLayout[i].0
let subLayout = layoutInstantPageBlock(webpage: webpage, userLocation: userLocation, rtl: rtl, block: subItem, boundingWidth: frame.width, horizontalInset: 0.0, safeInset: 0.0, isCover: false, previousItems: items, fillToSize: frame.size, media: media, mediaIndexCounter: &mediaIndexCounter, embedIndexCounter: &embedIndexCounter, detailsIndexCounter: &detailsIndexCounter, theme: theme, strings: strings, dateTimeFormat: dateTimeFormat, webEmbedHeights: webEmbedHeights, cachedMessageSyntaxHighlight: cachedMessageSyntaxHighlight, excludeCaptions: true)
let subLayout = layoutInstantPageBlock(webpage: webpage, userLocation: userLocation, rtl: rtl, block: subItem, boundingWidth: frame.width, horizontalInset: 0.0, safeInset: 0.0, isCover: false, previousItems: items, fillToSize: frame.size, media: media, mediaIndexCounter: &mediaIndexCounter, embedIndexCounter: &embedIndexCounter, detailsIndexCounter: &detailsIndexCounter, theme: theme, strings: strings, dateTimeFormat: dateTimeFormat, webEmbedHeights: webEmbedHeights, cachedMessageSyntaxHighlight: cachedMessageSyntaxHighlight, excludeCaptions: true, isLast: false)
items.append(contentsOf: subLayout.flattenedItemsWithOrigin(frame.origin))
i += 1
}
@ -753,8 +757,9 @@ public func layoutInstantPageBlock(webpage: TelegramMediaWebpage, userLocation:
}
var previousBlock: InstantPageBlock?
for subBlock in blocks {
let subLayout = layoutInstantPageBlock(webpage: webpage, userLocation: userLocation, rtl: rtl, block: subBlock, boundingWidth: boundingWidth - horizontalInset * 2.0 - lineInset, horizontalInset: 0.0, safeInset: 0.0, isCover: false, previousItems: items, fillToSize: nil, media: media, mediaIndexCounter: &mediaIndexCounter, embedIndexCounter: &embedIndexCounter, detailsIndexCounter: &detailsIndexCounter, theme: theme, strings: strings, dateTimeFormat: dateTimeFormat, webEmbedHeights: webEmbedHeights, cachedMessageSyntaxHighlight: cachedMessageSyntaxHighlight, excludeCaptions: false)
for i in 0 ..< blocks.count {
let subBlock = blocks[i]
let subLayout = layoutInstantPageBlock(webpage: webpage, userLocation: userLocation, rtl: rtl, block: subBlock, boundingWidth: boundingWidth - horizontalInset * 2.0 - lineInset, horizontalInset: 0.0, safeInset: 0.0, isCover: false, previousItems: items, fillToSize: nil, media: media, mediaIndexCounter: &mediaIndexCounter, embedIndexCounter: &embedIndexCounter, detailsIndexCounter: &detailsIndexCounter, theme: theme, strings: strings, dateTimeFormat: dateTimeFormat, webEmbedHeights: webEmbedHeights, cachedMessageSyntaxHighlight: cachedMessageSyntaxHighlight, excludeCaptions: false, isLast: i == blocks.count - 1)
let spacing = spacingBetweenBlocks(upper: previousBlock, lower: subBlock)
let blockItems = subLayout.flattenedItemsWithOrigin(CGPoint(x: horizontalInset + lineInset, y: contentSize.height + spacing))
@ -936,8 +941,9 @@ public func layoutInstantPageBlock(webpage: TelegramMediaWebpage, userLocation:
var subDetailsIndex = 0
var previousBlock: InstantPageBlock?
for subBlock in blocks {
let subLayout = layoutInstantPageBlock(webpage: webpage, userLocation: userLocation, rtl: rtl, block: subBlock, boundingWidth: boundingWidth, horizontalInset: horizontalInset, safeInset: safeInset, isCover: false, previousItems: subitems, fillToSize: nil, media: media, mediaIndexCounter: &mediaIndexCounter, embedIndexCounter: &embedIndexCounter, detailsIndexCounter: &subDetailsIndex, theme: theme, strings: strings, dateTimeFormat: dateTimeFormat, webEmbedHeights: webEmbedHeights, cachedMessageSyntaxHighlight: cachedMessageSyntaxHighlight, excludeCaptions: false)
for i in 0 ..< blocks.count {
let subBlock = blocks[i]
let subLayout = layoutInstantPageBlock(webpage: webpage, userLocation: userLocation, rtl: rtl, block: subBlock, boundingWidth: boundingWidth, horizontalInset: horizontalInset, safeInset: safeInset, isCover: false, previousItems: subitems, fillToSize: nil, media: media, mediaIndexCounter: &mediaIndexCounter, embedIndexCounter: &embedIndexCounter, detailsIndexCounter: &subDetailsIndex, theme: theme, strings: strings, dateTimeFormat: dateTimeFormat, webEmbedHeights: webEmbedHeights, cachedMessageSyntaxHighlight: cachedMessageSyntaxHighlight, excludeCaptions: false, isLast: i == blocks.count - 1)
let spacing = spacingBetweenBlocks(upper: previousBlock, lower: subBlock)
let blockItems = subLayout.flattenedItemsWithOrigin(CGPoint(x: 0.0, y: contentSize.height + spacing))
@ -1007,10 +1013,12 @@ public func layoutInstantPageBlock(webpage: TelegramMediaWebpage, userLocation:
contentSize.height += item.frame.height
items.append(item)
let inset: CGFloat = i == articles.count - 1 ? 0.0 : 17.0
let lineSize = CGSize(width: boundingWidth - inset, height: UIScreenPixel)
let shapeItem = InstantPageShapeItem(frame: CGRect(origin: CGPoint(x: rtl || item.rtl ? 0.0 : inset, y: contentSize.height - lineSize.height), size: lineSize), shapeFrame: CGRect(origin: CGPoint(), size: lineSize), shape: .rect, color: theme.controlColor)
items.append(shapeItem)
if !isLast {
let inset: CGFloat = i == articles.count - 1 ? 0.0 : 17.0
let lineSize = CGSize(width: boundingWidth - inset, height: UIScreenPixel)
let shapeItem = InstantPageShapeItem(frame: CGRect(origin: CGPoint(x: rtl || item.rtl ? 0.0 : inset, y: contentSize.height - lineSize.height), size: lineSize), shapeFrame: CGRect(origin: CGPoint(), size: lineSize), shape: .rect, color: theme.controlColor)
items.append(shapeItem)
}
}
return InstantPageLayout(origin: CGPoint(), contentSize: contentSize, items: items)
case let .map(latitude, longitude, zoom, dimensions, caption):
@ -1046,7 +1054,7 @@ public func layoutInstantPageBlock(webpage: TelegramMediaWebpage, userLocation:
}
}
public func instantPageLayoutForWebPage(_ webPage: TelegramMediaWebpage, instantPage: InstantPage?, userLocation: MediaResourceUserLocation, boundingWidth: CGFloat, safeInset: CGFloat, strings: PresentationStrings, theme: InstantPageTheme, dateTimeFormat: PresentationDateTimeFormat, webEmbedHeights: [Int : CGFloat] = [:], cachedMessageSyntaxHighlight: CachedMessageSyntaxHighlight? = nil) -> InstantPageLayout {
public func instantPageLayoutForWebPage(_ webPage: TelegramMediaWebpage, instantPage: InstantPage?, userLocation: MediaResourceUserLocation, boundingWidth: CGFloat, sideInset: CGFloat, safeInset: CGFloat, strings: PresentationStrings, theme: InstantPageTheme, dateTimeFormat: PresentationDateTimeFormat, webEmbedHeights: [Int : CGFloat] = [:], cachedMessageSyntaxHighlight: CachedMessageSyntaxHighlight? = nil, addFeedback: Bool = true) -> InstantPageLayout {
var maybeLoadedContent: TelegramMediaWebpageLoadedContent?
if case let .Loaded(content) = webPage.content {
maybeLoadedContent = content
@ -1074,8 +1082,9 @@ public func instantPageLayoutForWebPage(_ webPage: TelegramMediaWebpage, instant
var detailsIndexCounter: Int = 0
var previousBlock: InstantPageBlock?
for block in pageBlocks {
let blockLayout = layoutInstantPageBlock(webpage: webPage, userLocation: userLocation, rtl: rtl, block: block, boundingWidth: boundingWidth, horizontalInset: 17.0 + safeInset, safeInset: safeInset, isCover: false, previousItems: items, fillToSize: nil, media: media, mediaIndexCounter: &mediaIndexCounter, embedIndexCounter: &embedIndexCounter, detailsIndexCounter: &detailsIndexCounter, theme: theme, strings: strings, dateTimeFormat: dateTimeFormat, webEmbedHeights: webEmbedHeights, cachedMessageSyntaxHighlight: cachedMessageSyntaxHighlight, excludeCaptions: false)
for i in 0 ..< pageBlocks.count {
let block = pageBlocks[i]
let blockLayout = layoutInstantPageBlock(webpage: webPage, userLocation: userLocation, rtl: rtl, block: block, boundingWidth: boundingWidth, horizontalInset: sideInset + safeInset, safeInset: safeInset, isCover: false, previousItems: items, fillToSize: nil, media: media, mediaIndexCounter: &mediaIndexCounter, embedIndexCounter: &embedIndexCounter, detailsIndexCounter: &detailsIndexCounter, theme: theme, strings: strings, dateTimeFormat: dateTimeFormat, webEmbedHeights: webEmbedHeights, cachedMessageSyntaxHighlight: cachedMessageSyntaxHighlight, excludeCaptions: false, isLast: i == pageBlocks.count - 1)
let spacing = spacingBetweenBlocks(upper: previousBlock, lower: block)
let blockItems = blockLayout.flattenedItemsWithOrigin(CGPoint(x: 0.0, y: contentSize.height + spacing))
items.append(contentsOf: blockItems)
@ -1088,7 +1097,7 @@ public func instantPageLayoutForWebPage(_ webPage: TelegramMediaWebpage, instant
let closingSpacing = spacingBetweenBlocks(upper: previousBlock, lower: nil)
contentSize.height += closingSpacing
if webPage.webpageId.id != 0 {
if webPage.webpageId.id != 0 && addFeedback {
let feedbackItem = InstantPageFeedbackItem(frame: CGRect(x: 0.0, y: contentSize.height, width: boundingWidth, height: 40.0), webPage: webPage)
contentSize.height += feedbackItem.frame.height
items.append(feedbackItem)

103
submodules/InstantPageUI/Sources/InstantPageMultiTextAdapter.swift Normal file
View file

@ -0,0 +1,103 @@
import Foundation
import UIKit
import AsyncDisplayKit
import Display
import TelegramCore
public final class InstantPageMultiTextAdapter: ASDisplayNode, TextNodeProtocol {
private struct Entry {
let item: InstantPageTextItem
let charOffset: Int
let frameOrigin: CGPoint
}
private let entries: [Entry]
private let combinedString: NSAttributedString
public init(items: [InstantPageTextItem]) {
let separator = NSAttributedString(string: "\n\n")
let combined = NSMutableAttributedString()
var entries: [Entry] = []
for (index, item) in items.enumerated() {
let charOffset = combined.length
entries.append(Entry(item: item, charOffset: charOffset, frameOrigin: item.frame.origin))
combined.append(item.attributedString)
if index != items.count - 1 {
combined.append(separator)
}
}
self.entries = entries
self.combinedString = combined
super.init()
self.isUserInteractionEnabled = false
}
public var currentText: NSAttributedString? {
return self.combinedString
}
public func attributesAtPoint(_ point: CGPoint, orNearest: Bool) -> (Int, [NSAttributedString.Key: Any])? {
for entry in self.entries {
let localPoint = CGPoint(x: point.x - entry.frameOrigin.x, y: point.y - entry.frameOrigin.y)
if let (localIndex, attrs) = entry.item.attributesAtPoint(localPoint, orNearest: false) {
return (entry.charOffset + localIndex, attrs)
}
}
guard orNearest, !self.entries.isEmpty else {
return nil
}
var nearestEntry = self.entries[0]
var nearestDistance = CGFloat.greatestFiniteMagnitude
for entry in self.entries {
let frame = CGRect(origin: entry.frameOrigin, size: entry.item.frame.size)
let distance: CGFloat
if point.y < frame.minY {
distance = frame.minY - point.y
} else if point.y > frame.maxY {
distance = point.y - frame.maxY
} else {
distance = 0.0
}
if distance < nearestDistance {
nearestDistance = distance
nearestEntry = entry
}
}
let localPoint = CGPoint(x: point.x - nearestEntry.frameOrigin.x, y: point.y - nearestEntry.frameOrigin.y)
if let (localIndex, attrs) = nearestEntry.item.attributesAtPoint(localPoint, orNearest: true) {
return (nearestEntry.charOffset + localIndex, attrs)
}
return nil
}
public func textRangeRects(in range: NSRange) -> (rects: [CGRect], start: TextRangeRectEdge, end: TextRangeRectEdge)? {
var allRects: [CGRect] = []
var startEdge: TextRangeRectEdge?
var endEdge: TextRangeRectEdge?
for entry in self.entries {
let itemLength = entry.item.attributedString.length
let entryRange = NSRange(location: entry.charOffset, length: itemLength)
let intersection = NSIntersectionRange(range, entryRange)
if intersection.length == 0 {
continue
}
let localRange = NSRange(location: intersection.location - entry.charOffset, length: intersection.length)
guard let result = entry.item.textRangeRects(in: localRange) else {
continue
}
for rect in result.rects {
allRects.append(rect.offsetBy(dx: entry.frameOrigin.x, dy: entry.frameOrigin.y))
}
let translatedStart = TextRangeRectEdge(x: result.start.x + entry.frameOrigin.x, y: result.start.y + entry.frameOrigin.y, height: result.start.height)
let translatedEnd = TextRangeRectEdge(x: result.end.x + entry.frameOrigin.x, y: result.end.y + entry.frameOrigin.y, height: result.end.height)
if startEdge == nil {
startEdge = translatedStart
}
endEdge = translatedEnd
}
guard !allRects.isEmpty, let start = startEdge, let end = endEdge else {
return nil
}
return (allRects, start, end)
}
}

78
submodules/InstantPageUI/Sources/InstantPageTableItem.swift
View file

@ -144,54 +144,66 @@ public final class InstantPageTableItem: InstantPageScrollableItem {
}
public func drawInTile(context: CGContext) {
let hasBorder = self.borderWidth > 0.0
if hasBorder {
context.setStrokeColor(self.theme.tableBorderColor.cgColor)
context.setLineWidth(self.borderWidth)
}
context.setFillColor(self.theme.tableHeaderColor.cgColor)
let borderPath = CGMutablePath()
for cell in self.cells {
if cell.cell.text == nil {
continue
}
context.saveGState()
context.translateBy(x: cell.frame.minX, y: cell.frame.minY)
let hasBorder = self.borderWidth > 0.0
let bounds = CGRect(origin: CGPoint(), size: cell.frame.size)
var path: UIBezierPath?
if !cell.adjacentSides.isEmpty {
path = UIBezierPath(roundedRect: bounds, byRoundingCorners: cell.adjacentSides.uiRectCorner, cornerRadii: CGSize(width: tableCornerRadius, height: tableCornerRadius))
}
if cell.filled {
context.setFillColor(self.theme.tableHeaderColor.cgColor)
}
if self.borderWidth > 0.0 {
context.setStrokeColor(self.theme.tableBorderColor.cgColor)
context.setLineWidth(borderWidth)
}
if let path = path {
context.addPath(path.cgPath)
var drawMode: CGPathDrawingMode?
switch (cell.filled, hasBorder) {
case (true, false):
drawMode = .fill
case (true, true):
drawMode = .fillStroke
case (false, true):
drawMode = .stroke
default:
break
}
if let drawMode = drawMode {
context.drawPath(using: drawMode)
}
} else {
if cell.filled {
if cell.filled && cell.cell.text != nil {
if let path = path {
context.addPath(path.cgPath)
context.fillPath()
} else {
context.fill(bounds)
}
if hasBorder {
context.stroke(bounds)
}
}
if let textItem = cell.textItem {
textItem.drawInTile(context: context)
}
context.restoreGState()
if hasBorder {
if !cell.adjacentSides.contains(.top) {
borderPath.move(to: CGPoint(x: cell.frame.minX, y: cell.frame.minY))
borderPath.addLine(to: CGPoint(x: cell.frame.maxX, y: cell.frame.minY))
}
if !cell.adjacentSides.contains(.left) {
borderPath.move(to: CGPoint(x: cell.frame.minX, y: cell.frame.minY))
borderPath.addLine(to: CGPoint(x: cell.frame.minX, y: cell.frame.maxY))
}
}
}
if hasBorder && self.totalWidth > 0.0 {
let outerRect = CGRect(
x: self.borderWidth / 2.0,
y: self.borderWidth / 2.0,
width: self.totalWidth - self.borderWidth,
height: self.frame.height - self.borderWidth
)
borderPath.addPath(UIBezierPath(roundedRect: outerRect, cornerRadius: tableCornerRadius).cgPath)
}
if hasBorder {
context.addPath(borderPath)
context.strokePath()
}
}

122
submodules/InstantPageUI/Sources/InstantPageTextItem.swift
View file

@ -33,6 +33,12 @@ struct InstantPageTextStrikethroughItem {
let frame: CGRect
}
struct InstantPageTextUnderlineItem {
let frame: CGRect
let range: NSRange
let color: UIColor?
}
struct InstantPageTextImageItem {
let frame: CGRect
let range: NSRange
@ -68,17 +74,19 @@ public final class InstantPageTextLine {
let range: NSRange
public let frame: CGRect
let strikethroughItems: [InstantPageTextStrikethroughItem]
let underlineItems: [InstantPageTextUnderlineItem]
let markedItems: [InstantPageTextMarkedItem]
let imageItems: [InstantPageTextImageItem]
let formulaItems: [InstantPageTextFormulaRun]
public let anchorItems: [InstantPageTextAnchorItem]
let isRTL: Bool
init(line: CTLine, range: NSRange, frame: CGRect, strikethroughItems: [InstantPageTextStrikethroughItem], markedItems: [InstantPageTextMarkedItem], imageItems: [InstantPageTextImageItem], formulaItems: [InstantPageTextFormulaRun], anchorItems: [InstantPageTextAnchorItem], isRTL: Bool) {
init(line: CTLine, range: NSRange, frame: CGRect, strikethroughItems: [InstantPageTextStrikethroughItem], underlineItems: [InstantPageTextUnderlineItem], markedItems: [InstantPageTextMarkedItem], imageItems: [InstantPageTextImageItem], formulaItems: [InstantPageTextFormulaRun], anchorItems: [InstantPageTextAnchorItem], isRTL: Bool) {
self.line = line
self.range = range
self.frame = frame
self.strikethroughItems = strikethroughItems
self.underlineItems = underlineItems
self.markedItems = markedItems
self.imageItems = imageItems
self.formulaItems = formulaItems
@ -167,7 +175,7 @@ private func attachmentBoundsForRange(_ range: NSRange, line: InstantPageTextLin
}
public final class InstantPageTextItem: InstantPageItem {
let attributedString: NSAttributedString
public let attributedString: NSAttributedString
public let lines: [InstantPageTextLine]
let rtlLineIndices: Set<Int>
public var frame: CGRect
@ -264,6 +272,24 @@ public final class InstantPageTextItem: InstantPageItem {
context.fill(CGRect(x: itemFrame.minX, y: itemFrame.minY + floor((lineFrame.size.height / 2.0) + 1.0), width: itemFrame.size.width, height: 1.0))
}
}
if !line.underlineItems.isEmpty {
for item in line.underlineItems {
var color: UIColor? = item.color
if color == nil {
self.attributedString.enumerateAttributes(in: item.range, options: []) { attributes, _, _ in
if let foreground = attributes[NSAttributedString.Key.foregroundColor] as? UIColor {
color = foreground
}
}
}
if let color {
context.setFillColor(color.cgColor)
}
let itemFrame = item.frame.offsetBy(dx: lineFrame.minX, dy: 0.0)
context.fill(CGRect(x: itemFrame.minX, y: itemFrame.minY + lineFrame.size.height + 2.0, width: itemFrame.size.width, height: 1.0))
}
}
}
context.restoreGState()
@ -274,7 +300,7 @@ public final class InstantPageTextItem: InstantPageItem {
let boundsWidth = self.frame.width
for i in 0 ..< self.lines.count {
let line = self.lines[i]
let lineFrame = expandedFrameForLine(line, boundingWidth: boundsWidth, alignment: self.alignment)
if lineFrame.insetBy(dx: -5.0, dy: -5.0).contains(transformedPoint) {
var index = CTLineGetStringIndexForPosition(line.line, CGPoint(x: transformedPoint.x - lineFrame.minX, y: transformedPoint.y - lineFrame.minY))
@ -295,7 +321,53 @@ public final class InstantPageTextItem: InstantPageItem {
}
return nil
}
public func attributesAtPoint(_ point: CGPoint, orNearest: Bool) -> (Int, [NSAttributedString.Key: Any])? {
if let direct = self.attributesAtPoint(point) {
return direct
}
guard orNearest, !self.lines.isEmpty else {
return nil
}
let boundsWidth = self.frame.width
var nearestLineIndex = 0
var nearestDistance = CGFloat.greatestFiniteMagnitude
for i in 0 ..< self.lines.count {
let lineFrame = expandedFrameForLine(self.lines[i], boundingWidth: boundsWidth, alignment: self.alignment)
let distance: CGFloat
if point.y < lineFrame.minY {
distance = lineFrame.minY - point.y
} else if point.y > lineFrame.maxY {
distance = point.y - lineFrame.maxY
} else {
distance = 0.0
}
if distance < nearestDistance {
nearestDistance = distance
nearestLineIndex = i
}
}
let line = self.lines[nearestLineIndex]
let lineFrame = expandedFrameForLine(line, boundingWidth: boundsWidth, alignment: self.alignment)
let clampedX = max(lineFrame.minX, min(lineFrame.maxX, point.x))
var index = CTLineGetStringIndexForPosition(line.line, CGPoint(x: clampedX - lineFrame.minX, y: 0.0))
if index == self.attributedString.length {
index -= 1
} else if index != 0 {
var glyphStart: CGFloat = 0.0
CTLineGetOffsetForStringIndex(line.line, index, &glyphStart)
if clampedX - lineFrame.minX < glyphStart {
index -= 1
}
}
guard index >= 0, index < self.attributedString.length else {
return nil
}
return (index, self.attributedString.attributes(at: index, effectiveRange: nil))
}
private func attributeRects(name: NSAttributedString.Key, at index: Int) -> [CGRect]? {
var range = NSRange()
let _ = self.attributedString.attribute(name, at: index, effectiveRange: &range)
@ -370,9 +442,9 @@ public final class InstantPageTextItem: InstantPageItem {
guard range.length != 0 else {
return nil
}
let boundsWidth = self.frame.width
var rects: [(CGRect, CGRect)] = []
var startEdge: InstantPageTextRangeRectEdge?
var endEdge: InstantPageTextRangeRectEdge?
@ -393,11 +465,11 @@ public final class InstantPageTextItem: InstantPageItem {
rightOffset = ceil(secondaryOffset)
}
}
let lineFrame = expandedFrameForLine(line, boundingWidth: boundsWidth, alignment: self.alignment)
let width = max(0.0, abs(rightOffset - leftOffset))
if line.range.contains(range.lowerBound) {
let offsetX = floor(CTLineGetOffsetForStringIndex(line.line, range.lowerBound, nil))
startEdge = InstantPageTextRangeRectEdge(x: lineFrame.minX + offsetX, y: lineFrame.minY, height: lineFrame.height)
@ -411,7 +483,7 @@ public final class InstantPageTextItem: InstantPageItem {
let primaryOffset = floor(CTLineGetOffsetForStringIndex(line.line, range.upperBound - 1, &secondaryOffset))
secondaryOffset = floor(secondaryOffset)
let nextOffet = floor(CTLineGetOffsetForStringIndex(line.line, range.upperBound, &secondaryOffset))
if primaryOffset != secondaryOffset {
offsetX = secondaryOffset
} else {
@ -420,7 +492,7 @@ public final class InstantPageTextItem: InstantPageItem {
}
endEdge = InstantPageTextRangeRectEdge(x: lineFrame.minX + offsetX, y: lineFrame.minY, height: lineFrame.height)
}
rects.append((lineFrame, CGRect(origin: CGPoint(x: lineFrame.minX + min(leftOffset, rightOffset), y: lineFrame.minY), size: CGSize(width: width, height: lineFrame.size.height))))
}
}
@ -429,7 +501,16 @@ public final class InstantPageTextItem: InstantPageItem {
}
return nil
}
public func textRangeRects(in range: NSRange) -> (rects: [CGRect], start: TextRangeRectEdge, end: TextRangeRectEdge)? {
guard let result = self.rangeRects(in: range), let start = result.start, let end = result.end, !result.rects.isEmpty else {
return nil
}
let startEdge = TextRangeRectEdge(x: start.x, y: start.y, height: start.height)
let endEdge = TextRangeRectEdge(x: end.x, y: end.y, height: end.height)
return (result.rects, startEdge, endEdge)
}
public func lineRects() -> [CGRect] {
let boundsWidth = self.frame.width
var rects: [CGRect] = []
@ -909,9 +990,10 @@ func layoutTextItemWithString(_ string: NSAttributedString, boundingWidth: CGFlo
}
var strikethroughItems: [InstantPageTextStrikethroughItem] = []
var underlineItems: [InstantPageTextUnderlineItem] = []
var markedItems: [InstantPageTextMarkedItem] = []
var anchorItems: [InstantPageTextAnchorItem] = []
string.enumerateAttributes(in: lineRange, options: []) { attributes, range, _ in
if let _ = attributes[NSAttributedString.Key.strikethroughStyle] {
let lowerX = floor(CTLineGetOffsetForStringIndex(line, range.location, nil))
@ -919,6 +1001,16 @@ func layoutTextItemWithString(_ string: NSAttributedString, boundingWidth: CGFlo
let x = lowerX < upperX ? lowerX : upperX
strikethroughItems.append(InstantPageTextStrikethroughItem(frame: CGRect(x: workingLineOrigin.x + x, y: workingLineOrigin.y, width: abs(upperX - lowerX), height: fontLineHeight)))
}
if let _ = attributes[NSAttributedString.Key.underlineStyle] {
let lowerX = floor(CTLineGetOffsetForStringIndex(line, range.location, nil))
let upperX = ceil(CTLineGetOffsetForStringIndex(line, range.location + range.length, nil))
let x = lowerX < upperX ? lowerX : upperX
underlineItems.append(InstantPageTextUnderlineItem(
frame: CGRect(x: workingLineOrigin.x + x, y: workingLineOrigin.y, width: abs(upperX - lowerX), height: fontLineHeight),
range: range,
color: attributes[NSAttributedString.Key.underlineColor] as? UIColor
))
}
if let color = attributes[NSAttributedString.Key.init(rawValue: InstantPageMarkerColorAttribute)] as? UIColor {
var lineHeight = fontLineHeight
var delta: CGFloat = 0.0
@ -967,7 +1059,7 @@ func layoutTextItemWithString(_ string: NSAttributedString, boundingWidth: CGFlo
}
}
}
let textLine = InstantPageTextLine(line: line, range: lineRange, frame: CGRect(x: workingLineOrigin.x, y: workingLineOrigin.y, width: lineWidth, height: height), strikethroughItems: strikethroughItems, markedItems: markedItems, imageItems: lineImageItems, formulaItems: lineFormulaItems, anchorItems: anchorItems, isRTL: isRTL)
let textLine = InstantPageTextLine(line: line, range: lineRange, frame: CGRect(x: workingLineOrigin.x, y: workingLineOrigin.y, width: lineWidth, height: height), strikethroughItems: strikethroughItems, underlineItems: underlineItems, markedItems: markedItems, imageItems: lineImageItems, formulaItems: lineFormulaItems, anchorItems: anchorItems, isRTL: isRTL)
lines.append(textLine)
imageItems.append(contentsOf: lineImageItems)

3
submodules/InstantPageUI/Sources/InstantPageTextStyleStack.swift
View file

@ -197,6 +197,9 @@ final class InstantPageTextStyleStack {
if let link = link, let linkColor = linkColor {
attributes[NSAttributedString.Key.foregroundColor] = linkColor
if linkColor == color {
attributes[NSAttributedString.Key.underlineStyle] = NSUnderlineStyle.single.rawValue as NSNumber
}
if link, let linkMarkerColor = linkMarkerColor {
attributes[NSAttributedString.Key(rawValue: InstantPageMarkerColorAttribute)] = linkMarkerColor
}

62
submodules/InstantPageUI/Sources/InstantPageTheme.swift
View file

@ -4,23 +4,29 @@ import Display
import TelegramPresentationData
import TelegramUIPreferences
enum InstantPageFontStyle {
public enum InstantPageFontStyle {
case sans
case serif
}
struct InstantPageFont {
public struct InstantPageFont {
let style: InstantPageFontStyle
let size: CGFloat
let lineSpacingFactor: CGFloat
public init(style: InstantPageFontStyle, size: CGFloat, lineSpacingFactor: CGFloat) {
self.style = style
self.size = size
self.lineSpacingFactor = lineSpacingFactor
}
}
struct InstantPageTextAttributes {
public struct InstantPageTextAttributes {
let font: InstantPageFont
let color: UIColor
let underline: Bool
init(font: InstantPageFont, color: UIColor, underline: Bool = false) {
public init(font: InstantPageFont, color: UIColor, underline: Bool = false) {
self.font = font
self.color = color
self.underline = underline
@ -30,8 +36,8 @@ struct InstantPageTextAttributes {
return InstantPageTextAttributes(font: self.font, color: self.color, underline: underline)
}
func withUpdatedFontStyles(sizeMultiplier: CGFloat, forceSerif: Bool) -> InstantPageTextAttributes {
return InstantPageTextAttributes(font: InstantPageFont(style: forceSerif ? .serif : self.font.style, size: floor(self.font.size * sizeMultiplier), lineSpacingFactor: self.font.lineSpacingFactor), color: self.color, underline: self.underline)
func withUpdatedFontStyles(sizeMultiplier: CGFloat, lineSpacingFactor: CGFloat, forceSerif: Bool) -> InstantPageTextAttributes {
return InstantPageTextAttributes(font: InstantPageFont(style: forceSerif ? .serif : self.font.style, size: floor(self.font.size * sizeMultiplier), lineSpacingFactor: self.font.lineSpacingFactor * lineSpacingFactor), color: self.color, underline: self.underline)
}
}
@ -56,6 +62,17 @@ public struct InstantPageTextCategories {
let table: InstantPageTextAttributes
let article: InstantPageTextAttributes
public init(kicker: InstantPageTextAttributes, header: InstantPageTextAttributes, subheader: InstantPageTextAttributes, paragraph: InstantPageTextAttributes, caption: InstantPageTextAttributes, credit: InstantPageTextAttributes, table: InstantPageTextAttributes, article: InstantPageTextAttributes) {
self.kicker = kicker
self.header = header
self.subheader = subheader
self.paragraph = paragraph
self.caption = caption
self.credit = credit
self.table = table
self.article = article
}
func attributes(type: InstantPageTextCategoryType, link: Bool) -> InstantPageTextAttributes {
switch type {
case .kicker:
@ -77,8 +94,17 @@ public struct InstantPageTextCategories {
}
}
func withUpdatedFontStyles(sizeMultiplier: CGFloat, forceSerif: Bool) -> InstantPageTextCategories {
return InstantPageTextCategories(kicker: self.kicker.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, forceSerif: forceSerif), header: self.header.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, forceSerif: forceSerif), subheader: self.subheader.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, forceSerif: forceSerif), paragraph: self.paragraph.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, forceSerif: forceSerif), caption: self.caption.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, forceSerif: forceSerif), credit: self.credit.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, forceSerif: forceSerif), table: self.table.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, forceSerif: forceSerif), article: self.article.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, forceSerif: forceSerif))
func withUpdatedFontStyles(sizeMultiplier: CGFloat, lineSpacingFactor: CGFloat, forceSerif: Bool) -> InstantPageTextCategories {
return InstantPageTextCategories(
kicker: self.kicker.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, lineSpacingFactor: lineSpacingFactor, forceSerif: forceSerif),
header: self.header.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, lineSpacingFactor: lineSpacingFactor, forceSerif: forceSerif),
subheader: self.subheader.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, lineSpacingFactor: lineSpacingFactor, forceSerif: forceSerif),
paragraph: self.paragraph.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, lineSpacingFactor: lineSpacingFactor, forceSerif: forceSerif),
caption: self.caption.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, lineSpacingFactor: lineSpacingFactor, forceSerif: forceSerif),
credit: self.credit.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, lineSpacingFactor: lineSpacingFactor, forceSerif: forceSerif),
table: self.table.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, lineSpacingFactor: lineSpacingFactor, forceSerif: forceSerif),
article: self.article.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, lineSpacingFactor: lineSpacingFactor, forceSerif: forceSerif)
)
}
}
@ -132,8 +158,8 @@ public final class InstantPageTheme {
self.overlayPanelColor = overlayPanelColor
}
public func withUpdatedFontStyles(sizeMultiplier: CGFloat, forceSerif: Bool) -> InstantPageTheme {
return InstantPageTheme(type: type, pageBackgroundColor: pageBackgroundColor, textCategories: self.textCategories.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, forceSerif: forceSerif), serif: forceSerif, codeBlockBackgroundColor: codeBlockBackgroundColor, linkColor: linkColor, textHighlightColor: textHighlightColor, linkHighlightColor: linkHighlightColor, markerColor: markerColor, panelBackgroundColor: panelBackgroundColor, panelHighlightedBackgroundColor: panelHighlightedBackgroundColor, panelPrimaryColor: panelPrimaryColor, panelSecondaryColor: panelSecondaryColor, panelAccentColor: panelAccentColor, tableBorderColor: tableBorderColor, tableHeaderColor: tableHeaderColor, controlColor: controlColor, imageTintColor: imageTintColor, overlayPanelColor: overlayPanelColor)
public func withUpdatedFontStyles(sizeMultiplier: CGFloat, lineSpacingFactor: CGFloat, forceSerif: Bool) -> InstantPageTheme {
return InstantPageTheme(type: type, pageBackgroundColor: pageBackgroundColor, textCategories: self.textCategories.withUpdatedFontStyles(sizeMultiplier: sizeMultiplier, lineSpacingFactor: lineSpacingFactor, forceSerif: forceSerif), serif: forceSerif, codeBlockBackgroundColor: codeBlockBackgroundColor, linkColor: linkColor, textHighlightColor: textHighlightColor, linkHighlightColor: linkHighlightColor, markerColor: markerColor, panelBackgroundColor: panelBackgroundColor, panelHighlightedBackgroundColor: panelHighlightedBackgroundColor, panelPrimaryColor: panelPrimaryColor, panelSecondaryColor: panelSecondaryColor, panelAccentColor: panelAccentColor, tableBorderColor: tableBorderColor, tableHeaderColor: tableHeaderColor, controlColor: controlColor, imageTintColor: imageTintColor, overlayPanelColor: overlayPanelColor)
}
func headingTextAttributes(level: Int32, link: Bool) -> InstantPageTextAttributes {
@ -339,14 +365,14 @@ func instantPageThemeTypeForSettingsAndTime(themeSettings: PresentationThemeSett
public func instantPageThemeForType(_ type: InstantPageThemeType, settings: InstantPagePresentationSettings) -> InstantPageTheme {
switch type {
case .light:
return lightTheme.withUpdatedFontStyles(sizeMultiplier: fontSizeMultiplierForVariant(settings.fontSize), forceSerif: settings.forceSerif)
case .sepia:
return sepiaTheme.withUpdatedFontStyles(sizeMultiplier: fontSizeMultiplierForVariant(settings.fontSize), forceSerif: settings.forceSerif)
case .gray:
return grayTheme.withUpdatedFontStyles(sizeMultiplier: fontSizeMultiplierForVariant(settings.fontSize), forceSerif: settings.forceSerif)
case .dark:
return darkTheme.withUpdatedFontStyles(sizeMultiplier: fontSizeMultiplierForVariant(settings.fontSize), forceSerif: settings.forceSerif)
case .light:
return lightTheme.withUpdatedFontStyles(sizeMultiplier: fontSizeMultiplierForVariant(settings.fontSize), lineSpacingFactor: settings.lineSpacingFactor, forceSerif: settings.forceSerif)
case .sepia:
return sepiaTheme.withUpdatedFontStyles(sizeMultiplier: fontSizeMultiplierForVariant(settings.fontSize), lineSpacingFactor: settings.lineSpacingFactor, forceSerif: settings.forceSerif)
case .gray:
return grayTheme.withUpdatedFontStyles(sizeMultiplier: fontSizeMultiplierForVariant(settings.fontSize), lineSpacingFactor: settings.lineSpacingFactor, forceSerif: settings.forceSerif)
case .dark:
return darkTheme.withUpdatedFontStyles(sizeMultiplier: fontSizeMultiplierForVariant(settings.fontSize), lineSpacingFactor: settings.lineSpacingFactor, forceSerif: settings.forceSerif)
}
}

Some files were not shown because too many files have changed in this diff Show more