ios/README.md

# MusicBridge для iPhone

Нативный пульт на SwiftUI для MusicBridge.Agent на Windows. Звук играет на ПК.
Минимальная версия iOS — 17. Зависимостей Swift Package/CocoaPods нет.

## Возможности

- Сопряжение по HTTPS-адресу домашнего ПК, SHA-256 сертификата и коду.
- Сканирование QR агента камерой, открытие `musicbridge://pair?data=…` и ручной ввод.
- Поиск компьютера через Bonjour и восстановление адреса доверенного ПК.
- Проверка закреплённого DER-сертификата до отправки кода и при следующих соединениях.
- Хранение адреса, отпечатка и токена в Keychain только на этом устройстве.
- Название, исполнитель, обложка, позиция, play/pause, следующий/предыдущий трек,
  перемотка ползунком, системная громкость и mute.
- WSS-состояние, переподключение с задержкой, остановка сети в фоне и восстановление
  при возврате. Команды автоматически не повторяются.

**Статус:** пользователь подтвердил установку через iloader, рабочий пилот с
Windows-агентом и подключение по QR. В 0.4.0 добавлены иконка и обновлённый
интерфейс, в 0.5.0 — локальная Live Activity и Dynamic Island. CI собирает
приложение и расширение WidgetKit, выполняет XCTest и Release archive;
полная проверка устойчивости на физических устройствах остаётся в `PLAN.md`.

## Сборка на Mac

1. Открыть `MusicBridge.xcodeproj` в Xcode 27.
2. Выбрать схему MusicBridge и симулятор iPhone. Run запускает приложение,
   Test выполняет `MusicBridgeTests`.
3. Для физического iPhone выбрать свою Team в Signing & Capabilities. Сертификаты
   и provisioning profiles не хранить в Git. Bundle ID при необходимости сменить
   в `tools/generate_project.py`, затем повторно сгенерировать проект.
4. На ПК запустить агент с `--tray --lan`, открыть сопряжение. В приложении
   ввести адрес, отпечаток и код с экрана ПК. Разрешить доступ к локальной сети.

Проект уже сгенерирован и включён в Git; Python для обычной сборки не требуется.
После добавления Swift-файлов выполнить `python3 tools/generate_project.py`.
Структурная проверка на Windows/macOS: `python tools/validate_project.py`.

## GitHub Actions

`.github/workflows/ios.yml` собирает приложение и выполняет XCTest на `xcode-27`
при push в main, pull request или ручном запуске. Сохраняет лог, `.xcresult`
и ZIP приложения **для симулятора**, который нельзя установить на физический iPhone.
Apple ID и сертификаты для этой проверки не требуются. GitHub remote подключён:
`git@github.com:polskikh13/musicbridgeios.git`. GitHub CLI установлен и авторизован;
результаты доступны через `gh run list --repo polskikh13/musicbridgeios` и
`gh run view <run-id> --repo polskikh13/musicbridgeios --log-failed`.

Основной origin: `ssh://git@dev.yukinoki.ru:2222/musicbridge/ios.git`.
Отдельный remote `github` используется для Actions, основной origin сохранён.
Отправка: `git push origin main` и `git push github main`.
Код автоматически не зеркалируется между серверами. Локальная регрессионная
проверка выбора симулятора: `python tools/test_select_simulator.py`.

## Подключение через QR и поиск ПК

Откройте окно сопряжения в Windows-агенте (`--tray --lan`),
на iPhone нажмите «Сканировать QR» и разрешите камеру. После сканирования
нажмите «Подключить компьютер». Ссылки `musicbridge://` также открываются
из стандартной камеры. Приглашение должно быть свежим.

В разделе «Найти компьютер» можно выбрать найденный адрес. Сверьте **весь**
предложенный отпечаток с экраном ПК и введите код. Если поиск не работает,
проверьте доступ к локальной сети в настройках MusicBridge; ручной ввод остаётся.
При смене адреса уже доверенного ПК приложение пробует объявления с тем же
отпечатком и сохраняет новый адрес только после успешной TLS-проверки и авторизации.

## Установка на iPhone через Sideloadly

Пользователь также подтвердил установку через iloader. Для повторной установки
с Live Activity используйте версию **0.6.0 (build 7)**:
`build/iPhone-0.6.0-xcode27/MusicBridge-iPhone.ipa`. Выберите этот файл в iloader и
подпишите тем же Apple Account, которым установлена первая версия.

В 0.4.0 добавлены иконка, карточка QR, раскрываемые ручные поля, крупная
play/pause, процент громкости и меню компьютера. Размер обложки зависит от
доступной высоты окна; при крупном системном шрифте экран прокручивается.

Начиная с 0.3.0 обложка повторно загружается после временного сбоя, а после четырёх
неудачных попыток доступен ручной повтор. Отозванный доступ требует нового
сопряжения; автоматические попытки прекращаются. Если свернуть приложение во
время сопряжения, повторите его со свежим QR (удалив созданную запись на ПК,
если она уже успела появиться). При неизвестном результате команды проверьте
плеер перед повтором: приложение не повторяет команды автоматически.

Workflow также выполняет Release archive для `generic/platform=iOS` и создаёт
`MusicBridge-iPhone.ipa` в артефакте `MusicBridge-iPhone`. Это ARM64-сборка для
iOS 17+, без подписи. Подпись создаёт Sideloadly на вашем ПК с вашим Apple Account.
В Actions не передаются пароль Apple, сертификаты или provisioning profile.

1. Скачать артефакт MusicBridge-iPhone из успешного запуска Actions и распаковать
   ZIP артефакта, чтобы получить файл `.ipa`.
2. Подключить разблокированный iPhone к Windows кабелем; подтвердить доверие ПК.
3. Открыть Sideloadly, выбрать свой iPhone и файл `MusicBridge-iPhone.ipa`.
4. Войти в Apple Account непосредственно в Sideloadly, нажать Start, дождаться Done.
5. Если iPhone сообщает о недоверенном разработчике, открыть «Настройки → Основные
   → VPN и управление устройством», выбрать свой аккаунт и подтвердить доверие.
6. Для запуска включить «Настройки → Конфиденциальность и безопасность → Режим
   разработчика», затем выполнить предложенные iPhone перезагрузку и подтверждение.
7. Открыть MusicBridge, разрешить локальную сеть и выполнить сопряжение с ПК.

На бесплатном Apple Account подпись действует 7 дней; её нужно обновлять через
Sideloadly (в том числе его функцией автоматического обновления).
Файл MusicBridge-simulator.zip для установки на телефон не подходит.

[Sideloadly FAQ](https://sideloadly.io/faq) ·
[Apple: режим разработчика](https://developer.apple.com/documentation/Xcode/enabling-developer-mode-on-a-device)

## Live Activity и Dynamic Island — 0.6.0

После обновления с 0.5.0 уберите старую карточку кнопкой в приложении и нажмите
«Показать на экране блокировки» заново. Это связывает кнопки с текущим сопряжением
и переводит запись Keychain в режим доступа после первого разблокирования.
Токен остаётся только на этом устройстве, не копируется в виджет или UserDefaults.

На экране блокировки и в развёрнутом Dynamic Island доступны предыдущий трек,
play/pause, следующий трек и обновление. Компактный Island открывает приложение;
для кнопок удерживайте Island. Каждое действие выполняет отдельные HTTPS-запросы
с прежней проверкой сертификата. Оно работает через LiveActivityIntent в процессе
приложения, без открытия интерфейса; постоянного сетевого потока в фоне нет.

Перед командой считываются возможности плеера, затем команда отправляется один раз
и перечитывается состояние. Повторы команд отключены; при неизвестном результате
сначала используйте обновление. Одновременно выполняется одно действие карточки.
После закрытия карточки или удаления её связи с ПК новые команды не отправляются.
Для нового адреса ПК сначала откройте приложение: Bonjour-перенос адреса остаётся
в основном приложении. При отзыве доступа карточка завершается.

При обычном сворачивании показывается время последнего обновления, а не ошибка
«Данные устарели». Прогресс соответствует этому снимку. Реальная ошибка сети или
команды выводится на карточке. Изменения, сделанные непосредственно на ПК, при
приостановленном приложении не появятся сами: нажмите обновление или откройте плеер.
Для постоянных фоновых обновлений остаётся отдельная задача APNs.

В IPA есть расширение `MusicBridgeWidgets.appex`: iloader должен сохранить и подписать
его вместе с приложением. Проверка работы интентов в заблокированном состоянии и
системного отображения Island выполняется на iPhone; CI проверяет сборку, сетевую
логику команд и разметку. После перезагрузки сначала один раз разблокируйте iPhone.

### Встроенный музыкальный пульт iOS

Apple предлагает `RemoteMediaSession` в новом NowPlaying framework (iOS 27+)
для отображения музыки внешнего устройства на экране блокировки и в Control Center.
Это подходит архитектуре MusicBridge. Нужно отдельное расширение `com.apple.nowplaying.remote-media`. Сборка переведена на Xcode 27; 32 теста и Release archive прошли.
Эта интеграция исследована, но ещё не реализована. Для фоновых обновлений удалённых
сессий Apple также предоставляет push-механизм.
[Документация remote media sessions](https://developer.apple.com/documentation/nowplaying/publishing-remote-media-sessions).

## Источники

- [Apple: проверка доверия сервера](https://developer.apple.com/documentation/Foundation/performing-manual-server-trust-authentication)
- [Apple: доступ к локальной сети](https://developer.apple.com/documentation/technotes/tn3179-understanding-local-network-privacy)
- [GitHub: macOS runners](https://docs.github.com/en/actions/reference/runners/github-hosted-runners)
- [GitHub: лимиты и оплата Actions](https://docs.github.com/en/billing/concepts/product-billing/github-actions)

План и ограничения — в `PLAN.md`. Копия протокола агента — в `PROTOCOL.md`.

## Сервер сборки и фоновые обновления

GitHub Actions использует Apple Silicon runner `xcode-27` с проверкой версии Xcode.
SSH к локальной macOS-виртуалке настроен, однако она x86_64, без Xcode и не может
запускать Xcode 27. Для SDK 27 используется GitHub Actions.

Тестовый TLS-сервер требует `cryptography==46.0.3`; CI устанавливает пакет
в отдельное Python-окружение. Это зависимость тестов, не приложения.

Пользователь использует бесплатный Apple Account. APNs требует Push Notifications
capability и подписи с соответствующим provisioning profile, недоступных Personal Team.
Поэтому автоматическая фоновая доставка ещё не подключена. Команды Live Activity
выполняют запросы при нажатии; смена трека на ПК при приостановленном приложении
не обновляет карточку без запроса или push.