# Архитектура клиента (plugin.js)

Этот документ — карта для разработчика, открывающего [plugin.js](../plugin.js) впервые. Серверная сторона описана в [README.md](../README.md);

## Почему монолит

Весь клиент — один файл, который сервер отдаёт как `/music.js` (с подстановкой `{localhost}`, `{client_debug_enabled}`, `{stats_clear_enabled}` и `{daily_reset_enabled}` при отдаче). Это осознанное решение: файл монтируется в контейнер живьём, правка не требует пересборки, а Lampa загружает плагин одним запросом. Плата — размер (~17 тыс. строк), поэтому навигация построена на двух уровнях маркеров:

- `// ===== ИМЯ =====` — 14 крупных секций (список в шапке файла);
- `// --- имя ---` — подсекции внутри больших секций.

Шапка файла содержит карту секций, точки входа, легенду именований и typedef основных DTO — начинать чтение оттуда.

## Поток данных

### Главный экран

```
/music/home ──> MUSIC_HOME_CACHE (снапшот секций)
                │
                ├── локальные полки из Lampa.Storage: недавние
                │   поиски/альбомы/артисты, закладки, «Мои плейлисты»
                └── discovery-полки сервера (Apple Music, VK Top, SoundCloud)

карточка = entry (mapTrackCard / mapAlbumCard / mapArtistCard / mapPlaylistCard)
«Ещё» ──> /music/section?id=... (полный список, пагинация)
```

Recent-полки живут в `Lampa.Storage` и синхронизируются между экранами событием `MUSIC_RECENT_EVENT` — компоненты подписываются через `bindRecentListener` и обновляют только затронутую секцию, не перерисовывая home целиком.

После рестарта сервера discovery-провайдеры могут не успеть в 2-секундный бюджет `/music/home` — сервер тогда ставит `browse_sections_warming: true`, а клиент тихо дозапрашивает home (3s → 5s → 8s) и **доклеивает** недостающие полки в конец без перерисовки и потери фокуса (`homeLoadToken` гейтит устаревшие таймеры).

### Запуск трека

```
тап по треку
  └─> warmupStandaloneIosGesture()      — синхронно В ЖЕСТЕ (только player=ios)
  └─> /music/play?...                   — резолв источника на сервере
        └─> { track, selected_match, sources[] }
  └─> pickPlaybackSource(sources)       — m4a-first для ios-пути
  └─> buildResolvedPlayback()           — playback-объект
        ├─ player=ios   → startStandaloneIosAudioPlayback (свой <audio>)
        └─ player=inner → Lampa.Player.play (штатный плеер)
```

Все stream-URL ведут на серверный relay `/music/stream` — клиент не ходит на CDN напрямую.

### Прифетч-слой

Холодный резолв `/music/play` стоит секунды (YouTube-поиск + матчинг на сервере), поэтому кэш (`PLAY_PREFETCH_CACHE`, TTL 10 минут) греется заранее **тремя** независимыми механизмами. Все ходят через `requestPlay` (общий кэш + single-flight: повторный запрос присоединяется к летящему), только греют кэш и ничего не запускают:

| Прифетч | Триггер | Таймер |
| --- | --- | --- |
| `schedulePlayPrefetch` | `hover:focus` по карточке (ТВ-паттерн) | общий 180ms, «грей последнее под фокусом» |
| `scheduleNextTrackPrefetch` | ~3s после реального старта звука | свой; гейт поколением очереди; зеркалит арифметику embedded-next (`index+1` по `queueTracks`) |
| `scheduleFirstTrackPrefetch` | открытие экрана альбома/плейлиста | свой; 1 трек, на standalone iOS — стартовое окно `getStandaloneIosInitialResolveCount` треков (запуск там ждёт жадный резолв этого окна) |

Не переиспользовать таймеры между прифетчами — hover-семантика (сброс на каждом фокусе) конфликтует с отложенными.

Два инварианта тайминга вокруг кэша: cache-hit в `requestPlay` отдаёт ответ **строго асинхронно** (standalone-запуск рассчитан на резолв вне жеста), а `startStandaloneIosAudioPlayback` держит **session-settle** ~700ms между жестовым silent-warmup и прицеплением реального src — iOS фиксирует capabilities Now Playing в первые сотни ms сессии, мгновенная подмена src строила сессию на emptied-элементе.

### Мёртвый трек в очереди

Провал резолва — не тупик: на **честный** отказ сервера (`available: false`) очередь автоматически шагает дальше (`maybeAutoSkipUnavailableTrack`), сетевой сбой (`null`/битый ответ) — стоп, как раньше (iOS душит сеть скрытой страницы — авто-скип прощёлкал бы живые треки под локскрином). Кап 3 скипа подряд, счётчик сбрасывается только на реальном старте звука; repeat-one не скипается.

## Два режима воспроизведения

| | `player=ios` (standalone) | `player=inner` (embedded) |
| --- | --- | --- |
| Media owner | собственный `<audio>` модуля | видеоэлемент `Lampa.PlayerVideo` |
| UI | мини-бар + фулл-плеер (свайпы, шиты) | штатный интерфейс Lampa |
| Lock screen | полный: play/pause/prev/next/скраббер | play/pause/prev/next, без скраббера |
| Состояние | `MUSIC_IOS_AUDIO` | `MUSIC_EMBEDDED_IOS` |
| Код | секции QUEUE / IOS PLAYBACK, IOS FULL PLAYER | подсекция embedded в IOS FULL PLAYER + LAMPA PLAYER BRIDGE |

Режимы нельзя смешивать: у них разные media owner и разная логика Media Session. Почему в embedded-режиме нет скраббера — разобрано в [ios-embedded-lockscreen-seek.md](./ios-embedded-lockscreen-seek.md).

## Жизненный цикл standalone iOS-плеера

Это самая хрупкая зона модуля. Каждый шаг ниже существует из-за конкретного поведения iOS/WebKit; подробности — в «почему»-комментариях у функций.

```
тап «играть» (жестовый контекст!)
  ├─ warmupStandaloneIosGesture()   тихий play() выдаёт элементу user-gesture
  │                                 кредит — иначе iOS игнорирует lock-screen команды
  ├─ armStandaloneIosMediaSessionHandlers()
  │                                 все обработчики ДО первого play(): iOS фиксирует
  │                                 возможности Now Playing при создании сессии
  └─ startStandaloneIosKeepAlive()  Web Audio-контекст держит аудио-сессию,
                                    чтобы resume работал на заблокированном экране

играет трек
  ├─ timeupdate → обновление бара/фулл-плеера (UI-ключи против лишних перерисовок)
  ├─ maybeSyntheticStandaloneIosEnded()  ручной автопереход: WebKit парсит
  │                                      YouTube fMP4 с удвоенной длительностью,
  │                                      штатный 'ended' не стреляет
  └─ scheduleStandaloneIosLockKick()     pause()+play() через 400ms после
                                         блокировки — включает скраббер

команда с lock screen (play/pause/seekto)
  ├─ pause-as-play: повторный pause на стоящем треке при живом keep-alive = play
  └─ watchStandaloneIosPlayProgress()    watchdog: резолв play() не доказывает
        ├─ attempt 0: pause()+play()     звук — проверяем прогресс currentTime
        └─ attempt 1: recoverStandaloneIosPlayback (переприцепка src, страховка)

stop / конец плейлиста
  └─ stopStandaloneIosKeepAlive(), снапшот очереди очищается
```

## Снапшот очереди (v2)

Очередь переживает перезапуск клиента через два ключа `Lampa.Storage` — разнесены, чтобы частый тик не пересобирал всю очередь (это грело телефон):

- `queue_blob_v2` — окно ≤500 треков + режимы (repeat/shuffle/провайдер) + `snapshotId`; пишется **по событиям** (смена трека/состава, toggles, приближение к краю окна);
- `queue_position_v2` — крошечная запись `snapshotId`/`trackId`/`currentTime`; пишется каждые 4 секунды.

Связка через `snapshotId`: позиция от чужого поколения блоба игнорируется. TTL 14 дней считается по свежести позиции. Restore читает v2 с fallback на legacy-ключ v1. `snapshotId` также служит маркером поколения очереди для радио (один запрос автоподборки на поколение).

## Радио на клиенте

Два входа, одна настройка (`radio_autoplay_enabled`): тумблер в фильтре и чип «Подборка» в фулл-плеере. Автоподборка триггерится, когда играет предпоследний трек **по порядку воспроизведения** (при shuffle — по `standaloneIosOrder`, не по физическому индексу); guard — один POST `/music/radio` на поколение очереди + `pending`-флаг. Клиент шлёт seed-треки и `exclude` всей очереди (сервер её не видит). Добавленные треки несут флаг `auto_radio` (едет в снапшот), в шите очереди перед первым из них — разделитель «Дальше автоподборка». «Радио от трека» (`startRadioFromTrack`) строит **новую** очередь: сид первым, волна следом; при неудаче текущая очередь не трогается. `repeat=all`, restored-очередь до play и внешние m3u-плееры автоподборку отключают.

## Анти-гонки

Асинхронные колбэки защищены токенами (`prepareToken`, `playWatchToken`, `switchToken`, `MUSIC_PLAY_LAUNCH_TOKEN`, `homeLoadToken`): перед применением результата колбэк сверяет токен с текущим и молча выходит, если операция устарела (пользователь переключил трек, начался новый watch). `MUSIC_PLAY_LAUNCH_TOKEN` — last-tap-wins для `playTrack`: каждый вызов инвалидирует незавершённые флоу предыдущего, стейловый запуск не доезжает до плеера (раньше двойной тап по медленно резолвящемуся треку давал два одновременных плеера). Новых async-путей это правило тоже касается.

## Отладка

- `client_debug_enabled: true` в конфиге модуля → `traceStandaloneIosAudio` и heat-метрики шлют события на `/music/clientlog`, сервер пишет их в лог. Это единственный способ отлаживать lock screen на реальном iPhone. После отладки — выключить.
- Имена трейсов стабильные (`play-nudge-ok`, `keepalive-start`, `media-session-pause-as-play`…) — по ним можно грепать историю в логах контейнера.

## Глоссарий

| Термин | Значение |
| --- | --- |
| entry | карточка полки: `{ type, id, title, subtitle, badge, image, raw }` |
| section | полка home или полный экран списка (`/music/section`) |
| match | кандидат audio-источника для трека (`MusicAudioMatch`) |
| pinned | ручной выбор источника; авторитетнее любых эвристик, живёт в SQLite |
| warmup | тихий `play()` синхронно в жесте — выдаёт user-gesture кредит |
| keep-alive | беззвучный Web Audio-контекст, держит аудио-сессию во время паузы |
| nudge | цикл `pause()+play()` — единственное, что размораживает clock элемента |
| lock-kick | rate-переход после блокировки, включающий скраббер на lock screen (на бете iOS 27 не действует — сломано платформой) |
| session-settle | выдержка ~700ms между warmup и реальным src: iOS фиксирует capabilities сессии в первые сотни ms |
| auto-skip | автопропуск трека с честным `available: false`; кап 3 подряд, сеть не скипается |
| warming | `browse_sections_warming` в `/music/home`: полки ещё греются, клиент дозапросит и доклеит |
| synthetic-ended | ручной автопереход, когда WebKit завысил длительность и `'ended'` не стреляет |
| sane-duration | выбор между длительностью стрима и метаданных при диком расхождении |
| snapshot / restore | сохранение очереди в Storage (blob + position, v2) и восстановление после перезапуска |
| snapshotId | поколение очереди: связывает blob с позицией, гейтит радио-запросы |
| auto_radio | флаг трека, добавленного автоподборкой; рисует разделитель в очереди |
| heat-метрики | счётчики горячих путей, уходят на `/music/clientlog` при отладке |

## Правила изменений

1. После правки `plugin.js` поднять revision в `lampac-docker/plugins/override/lampainit-invc.js`, иначе клиенты держат кэшированный JS.
2. Всё, что касается standalone iOS-плеера, тестировать на реальном iPhone с заблокированным экраном — симулятор и десктоп-браузер не воспроизводят поведение аудио-сессий iOS.
3. Не удалять «бессмысленные» на вид pause/play-циклы и таймауты — почти каждый из них компенсирует конкретное поведение iOS (см. комментарии). История экспериментов: [ios-embedded-lockscreen-seek.md](./ios-embedded-lockscreen-seek.md).