Wire local TDLib into iOS FFI build

docs/ios/tdlib-linking.md

@@ -7,7 +7,7 @@ Local toolchain status:
 - `scripts/check-ios-prereqs.sh` passes.
 - `scripts/run-ios-simulator-app.sh` launches the fake-backed SwiftUI shell in iOS Simulator.
 
-Current real TDLib blocker:
+Previous real TDLib blocker:
 
 ```bash
 DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer cargo build -p tele-ios-ffi --target aarch64-apple-ios-sim --release
@@ -25,10 +25,83 @@ Interpretation:
 
 - Rust, Swift, Xcode, and the iOS simulator runtime are working.
 - The fake-backed iOS app shell can be built, installed, launched, and rendered.
-- Real TDLib iOS linking is blocked because `tdlib-rs` 1.2.0 does not publish the iOS static library artifact requested by its `download-tdlib` build script.
+- `download-tdlib` cannot be used for iOS because `tdlib-rs` 1.2.0 does not publish the iOS artifact requested by its build script.
 
-Next viable paths:
+Current real TDLib status:
 
-1. Build TDLib for `iphoneos` and `iphonesimulator` locally and switch the Rust dependency path to `local-tdlib` or `pkg-config`.
-2. Add a fake-only `tele-ios-ffi` build feature that avoids linking TDLib for simulator UI work, while keeping real TDLib behind a separate feature.
-3. Replace the `tdlib-rs` packaging path for iOS with a lower-level C ABI/XCFramework if UniFFI plus `tdlib-rs` cannot link cleanly on device.
+- `scripts/build-tdlib-ios.sh` builds TDLib `1.8.29` locally for iOS device and simulator.
+- `.build/tdlib-ios/iphoneos/lib/libtdjson.1.8.29.dylib` is `arm64`.
+- `.build/tdlib-ios/iphonesimulator/lib/libtdjson.1.8.29.dylib` is a universal `x86_64` + `arm64` simulator dylib.
+- `scripts/check-ios-tdlib-linking.sh` builds `tele-ios-ffi` for `aarch64-apple-ios-sim` with local TDLib.
+- `IOS_RUST_TARGET=aarch64-apple-ios scripts/build-ios-ffi-with-local-tdlib.sh` builds `tele-ios-ffi` for device with local TDLib.
+- `scripts/build-ios-real-ffi-xcframework.sh` packages simulator Rust slices into `tele_ios_ffi.xcframework`, packages local `libtdjson` into `tdjson.xcframework`, and writes generated Swift bindings into the Swift package's local `Generated` path.
+- `TELE_IOS_USE_LOCAL_FFI=1 scripts/build-ios-simulator-app.sh` builds and packages the SwiftUI simulator app against the real Rust/TDLib FFI path, including `Frameworks/libtdjson.dylib` in the `.app` bundle.
+- The repo patches `tdlib-rs` through `crates/vendor/tdlib-rs` because upstream `src/build.rs` does not handle `target_os = "ios"` for `local-tdlib`.
+
+Selected path:
+
+1. Keep `download-tdlib` for the terminal/macOS build path.
+2. Build TDLib locally for iOS and iOS Simulator from the TDLib source commit matching TDLib `1.8.29`.
+3. Build `tele-ios-ffi` with `tele-core/tdlib-local` and `LOCAL_TDLIB_PATH`.
+4. Package the resulting Rust FFI library and TDLib dylib into the iOS app/XCFramework path.
+
+The TDLib source commit used for `1.8.29` is:
+
+```text
+af69dd4397b6dc1bf23ba0fd0bf429fcba6454f6
+```
+
+This can be checked with:
+
+```bash
+npm info prebuilt-tdlib@td-1.8.29 tdlib --json
+```
+
+Build local TDLib artifacts:
+
+```bash
+DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer scripts/build-tdlib-ios.sh
+```
+
+This writes local, untracked outputs to:
+
+```text
+.build/tdlib-ios/iphoneos/
+.build/tdlib-ios/iphonesimulator/
+```
+
+Build the real iOS FFI path against local TDLib:
+
+```bash
+DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer scripts/build-ios-ffi-with-local-tdlib.sh
+```
+
+or for a device target:
+
+```bash
+DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer IOS_RUST_TARGET=aarch64-apple-ios scripts/build-ios-ffi-with-local-tdlib.sh
+```
+
+Package the real FFI path for the Swift app and build the simulator `.app`:
+
+```bash
+DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer scripts/build-ios-real-ffi-xcframework.sh
+TELE_IOS_USE_LOCAL_FFI=1 DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer scripts/build-ios-simulator-app.sh
+```
+
+Known local prerequisites:
+
+- Xcode with the iOS SDK installed.
+- Homebrew build tools: `brew install cmake gperf coreutils`.
+- Rust iOS targets: `rustup target add aarch64-apple-ios-sim aarch64-apple-ios`.
+- `scripts/build-tdlib-ios.sh` builds only the required OpenSSL platforms through TDLib's vendored `Python-Apple-support` flow, with a local patch for the simulator target triple under Xcode 26.
+- TDLib CMake uses `TDLIB_IOS_DEPLOYMENT_TARGET=17.0` by default to match the Swift package minimum iOS version.
+- TDLib's `prepare_cross_compiling` target is run as a host-side generation step before cross-compiling, so generated TL/MIME sources exist for the iOS build.
+
+Example local blocker if these tools are missing:
+
+```text
+Required tool not found: cmake
+```
+
+CMake 4.x compatibility is handled by passing `-DCMAKE_POLICY_VERSION_MINIMUM=3.5` to TDLib's configure step.

docs/superpowers/plans/2026-05-20-ios-app-roadmap.md

@@ -45,6 +45,33 @@ Architecture default: Rust `tele-core` remains the source of Telegram state and
   - Swift sample test can create a fake session, receive events, load chats, open a chat, send a message, react, and search.
   - Real TDLib linking is validated for iOS simulator and device or documented as blocked with exact linker error.
 
+#### Phase 2A: Local TDLib for iOS
+
+`tdlib-rs` 1.2.0 with `download-tdlib` downloads prebuilt TDLib archives from `FedericoBruzzone/tdlib-rs` releases using the pattern `tdlib-{tdlib_version}-{target_os}-{target_arch}.zip`. The terminal/macOS build works because the macOS archive exists. The iOS archives, for example `tdlib-1.8.29-ios-aarch64.zip`, are not published, so iOS real linking must not depend on `download-tdlib`.
+
+- Keep `download-tdlib` for the terminal/macOS build path while it remains useful there.
+- Switch the iOS FFI build path to `tdlib-rs` `local-tdlib` support.
+- Pin the local TDLib build to the TDLib version expected by `tdlib-rs` 1.2.0: `1.8.29`.
+- Add `scripts/build-tdlib-ios.sh` to build TDLib locally for:
+  - `arm64-apple-ios`
+  - `arm64-apple-ios-sim`
+  - optionally `x86_64-apple-ios-sim` if Intel Mac simulator support is needed.
+- Store generated TDLib artifacts outside git, for example:
+  - `.build/tdlib-ios/iphoneos/include`
+  - `.build/tdlib-ios/iphoneos/lib`
+  - `.build/tdlib-ios/iphonesimulator/include`
+  - `.build/tdlib-ios/iphonesimulator/lib`
+- Add `scripts/build-ios-ffi-with-local-tdlib.sh` to set `LOCAL_TDLIB_PATH` and build `tele-ios-ffi` for simulator/device targets.
+- Patch `tdlib-rs` through `crates/vendor/tdlib-rs` until upstream handles `target_os = "ios"` in its `local-tdlib` build helper.
+- Run TDLib's host-side `prepare_cross_compiling` target before the iOS cross-build, because TDLib 1.8.29 expects generated TL/MIME sources to exist during cross-compilation.
+- After simulator and device Rust builds link, package the Rust FFI output and TDLib dependency into an iOS-consumable XCFramework or documented adjacent native dependency.
+- Acceptance:
+  - `scripts/check-ios-tdlib-linking.sh` no longer fails because of a missing GitHub release archive. Completed on 2026-05-21.
+  - `cargo build -p tele-ios-ffi --target aarch64-apple-ios-sim --release` links with local TDLib. Completed on 2026-05-21 through `scripts/check-ios-tdlib-linking.sh`.
+  - `cargo build -p tele-ios-ffi --target aarch64-apple-ios --release` links with local TDLib. Completed on 2026-05-21 through `IOS_RUST_TARGET=aarch64-apple-ios scripts/build-ios-ffi-with-local-tdlib.sh`.
+  - The Xcode app can be built against the real FFI path, not only the fake bridge. Completed on 2026-05-21 through `scripts/build-ios-real-ffi-xcframework.sh` and `TELE_IOS_USE_LOCAL_FFI=1 scripts/build-ios-simulator-app.sh`.
+  - Any remaining CMake/OpenSSL/zlib/linker blockers are documented with the exact command and error text.
+
 ### Phase 3: iOS App Shell
 
 - Add native app under `apps/ios/TeleTuiIOS`.