vimp-engine 0.38.2 → 0.39.0

package/src/client/main.js

@@ -26,13 +26,16 @@ import StatCtrl from './components/controller/Stat.js';
 import VoteModel from './components/model/Vote.js';
 import VoteView from './components/view/Vote.js';
 import VoteCtrl from './components/controller/Vote.js';
+import VoiceModel from './components/model/Voice.js';
+import VoiceView from './components/view/Voice.js';
+import VoiceCtrl from './components/controller/Voice.js';
 import {
   buildForm,
   mergeRoomDefaults,
   bindLiveErrors,
 } from './lib/formBuilder.js';
 import { normalizeAuthParams } from './lib/authParams.js';
-import { renderProjectLink } from './lib/footerLink.js';
+import { renderDocsLink } from './lib/footerLink.js';
 import { createGameActivator } from './lib/gameActivator.js';
 import createAutostart from './lib/autostart.js';
 import { applyCatalogState } from './lib/catalogState.js';
@@ -45,7 +48,10 @@ import {
 import { createContextTracker } from './lib/contextTracker.js';
 import { createLocalPlayer } from './lib/localPlayer.js';
 import { createAccolades } from './lib/accolades.js';
+import { createVoiceState } from './lib/voiceState.js';
+import { parseVoiceMessage } from '../lib/voiceMessages.js';
 import { createDiagnostics } from './lib/diagnostics.js';
+import { fetchRetrying, isNetworkFailure } from './lib/retryOnNetworkError.js';
 import { dispatchSocketMessage } from './lib/socketDispatch.js';
 import { pickActiveGame, isGameAvailable } from './lib/pickActiveGame.js';
 import { readCoreAbi, dispatchCoreOp, ABI_UNKNOWN } from '../lib/coreAbi.js';
@@ -183,13 +189,25 @@ function bindActiveGame(manifest, plugin) {
 const injectedBoot = getBootConfig();
 const manifestPromise = injectedBoot
   ? null
-  : fetchGamesManifest(lobbyConfig.gamesManifestUrl).catch(err => err);
+  : fetchGamesManifest(lobbyConfig.gamesManifestUrl, (...args) =>
+      fetchRetrying(fetch, ...args),
+    ).catch(err => err);
+
+let boot;
+
+try {
+  boot = injectedBoot ?? (await resolveBootConfig());
+} catch (e) {
+  // сети нет и режим неизвестен: репортёр ещё не создан (ему нужен режим),
+  // игроку остаётся надпись отказа
+  showBootFailure(`Failed to load the game: ${e.message}`);
+  throw e;
+}
 
-const boot = injectedBoot ?? (await resolveBootConfig());
 const bootMode = boot.mode;
 const isLobbyMode = bootMode === 'lobby';
 
-// журнал клиентских ошибок (plan/client-reports): ставится как можно
+// журнал клиентских ошибок: ставится как можно
 // раньше, чтобы ловить и сбои самого старта. Лобби и dedicated шлют на
 // свой бокс; SDK (solo) — только если встраивающий передал reportUrl
 const diagnostics = createDiagnostics({
@@ -273,6 +291,12 @@ try {
   }
 } catch (e) {
   showBootFailure(`Failed to load the game: ${e.message}`, gameContainer);
+
+  // сбой сети — не ошибка кода: в журнал он не уходит
+  if (isNetworkFailure(e)) {
+    diagnostics.ignore(e);
+  }
+
   throw e;
 }
 
@@ -294,6 +318,7 @@ const PS_CHAT_DATA = wsports.server.CHAT_DATA;
 const PS_VOTE_DATA = wsports.server.VOTE_DATA;
 const PS_KEYSET_DATA = wsports.server.KEYSET_DATA;
 const PS_ACCOLADES_DATA = wsports.server.ACCOLADES_DATA;
+const PS_VOICE_DATA = wsports.server.VOICE_DATA;
 const PS_SESSION_DATA = wsports.server.SESSION_DATA;
 const PS_RESUME_RESULT = wsports.server.RESUME_RESULT;
 
@@ -306,6 +331,7 @@ const PC_MAP_READY = wsports.client.MAP_READY;
 const PC_FIRST_SHOT_READY = wsports.client.FIRST_SHOT_READY;
 const PC_KEYS_DATA = wsports.client.KEYS_DATA;
 const PC_CHAT_DATA = wsports.client.CHAT_DATA;
+const PC_VOICE_FLOOR = wsports.client.VOICE_FLOOR;
 const PC_VOTE_DATA = wsports.client.VOTE_DATA;
 const PC_PONG = wsports.client.PONG;
 const PC_LEAVE = wsports.client.LEAVE;
@@ -348,8 +374,8 @@ const renderContexts = {};
 // контекста (хост её повторно не пришлёт)
 let lastMapData = null;
 
-// dev-сборка (Vite подставляет константу): включает отладочный контур этапа 6
-// плана plan/done/ai-debug — рекордер в комнате и window.__vimpDebug. В прод-бандле
+// dev-сборка (Vite подставляет константу): включает отладочный контур —
+// рекордер в комнате и window.__vimpDebug. В прод-бандле
 // ветка вырезается сборкой, поведение не меняется
 const isDevBuild =
   typeof import.meta.env !== 'undefined' && import.meta.env.DEV === true;
@@ -414,6 +440,15 @@ const localPlayer = createLocalPlayer(() => clientCore);
 // сервис пула зависимостей: «какое место у этой сущности в глобальном
 // топе?». Места считает хост, part рисует за них знак (см. lib/accolades.js)
 const accolades = createAccolades();
+// голосовая связь: кто в эфире (сервис партов `voice`) — хранилище пишет
+// движок по VOICE_DATA, парты только читают (lib/voiceState.js)
+const voice = createVoiceState();
+// подсистема голоса грузится лениво — только у игры с включённой связью
+let voiceClient = null;
+let voiceConfig = null;
+// номер запуска подсистемы: чанк, догрузившийся после закрытия матча,
+// уничтожает свой клиент сам
+let voiceSession = 0;
 let inputSeq = 0; // номер отправленного ввода (KEYS_DATA)
 
 // обратный индекс снапшот-схемы игры (CONFIG_DATA.snapshot):
@@ -432,6 +467,9 @@ socketMethods[PS_CONFIG_DATA] = async data => {
     return;
   }
 
+  voiceConfig = data.voice ?? null;
+  voice.store.setEnabled(voiceConfig?.enabled === true);
+
   gameSets = data.parts.gameSets;
   entitiesOnCanvas = data.parts.entitiesOnCanvas;
 
@@ -522,12 +560,15 @@ socketMethods[PS_CONFIG_DATA] = async data => {
       // места в глобальном топе: знак за место рисует part игры, движок
       // раздаёт только числа (см. lib/accolades.js)
       accolades,
+      // индикаторы эфира связи для партов игры: кто сейчас говорит
+      // (только чтение, см. lib/voiceState.js)
+      voice: voice.service,
       // база ассетов игры — тем же каналом, что и путь к звукам (см. выше):
       // картинки карт живут в пакете игры (dist/img/), движок их не раздаёт.
       // part, объявивший сервис в componentDependencies, строит URL сам —
       // движок не знает ни имён файлов, ни их раскладки внутри пакета
       assetsBase: activeGameManifest.assetsBase,
-      // журнал клиентских ошибок для партов игры (plan/client-reports):
+      // журнал клиентских ошибок для партов игры:
       // warn(code, details) — своё предупреждение, capture(error) — пойманная
       // ошибка. Сервис опционален: игра не пишет его в requires
       diagnostics: {
@@ -577,21 +618,19 @@ socketMethods[PS_AUTH_DATA] = data => {
 
   document.getElementById('logo').textContent = texts?.title || 'VIMP';
 
-  // футер формы входа: версия и ссылка пакета ИГРЫ. Здесь, а не в AuthView:
-  // его elems приходят из authSchema.elems игрового плагина, и футер каркаса
-  // — не его забота. Метаданные кладёт в манифест мастер (GameCatalog читает
-  // package.json пакета); в standalone-манифесте их может не быть — тогда
-  // ячейки пустые, раскладку space-between это не ломает
+  // футер формы входа: версия пакета ИГРЫ и (в dev-сборке) ссылка на
+  // документацию. Здесь, а не в AuthView: его elems приходят из
+  // authSchema.elems игрового плагина, и футер каркаса — не его забота.
+  // Версию кладёт в манифест мастер (GameCatalog читает package.json
+  // пакета); в standalone-манифесте её может не быть — тогда ячейка пустая,
+  // раскладку space-between это не ломает
   const authVersion = document.getElementById('auth-version');
 
   if (authVersion) {
     authVersion.textContent = activeGameManifest?.packageVersion ?? '';
   }
 
-  renderProjectLink(
-    document.getElementById('auth-package-link'),
-    activeGameManifest?.packageUrl,
-  );
+  renderDocsLink(document.getElementById('auth-docs-link'), isDevBuild);
 
   // память клиента (localStorage) + принудительное значение поля с
   // единственным вариантом. Здесь, а не в AuthView: solo-путь ниже отвечает
@@ -892,6 +931,19 @@ socketMethods[PS_ACCOLADES_DATA] = data => {
   modules.stat?.applyAccolades?.();
 };
 
+// голосовая связь: кортеж разбирается один раз (lib/voiceMessages.js) —
+// хост в P2P чужой, непрошедшее проверку не доходит ни до кого
+socketMethods[PS_VOICE_DATA] = data => {
+  const message = parseVoiceMessage(data);
+
+  if (!message) {
+    return;
+  }
+
+  voice.store.apply(message);
+  voiceClient?.handleFloorMessage(message);
+};
+
 // chat data
 socketMethods[PS_CHAT_DATA] = data => {
   modules.chat.add(data);
@@ -1034,7 +1086,7 @@ socketMethods[PS_RESUME_RESULT] = data => {
 };
 
 // console: логи авторитетной половины (Worker изолирован от DevTools вкладки —
-// иначе его события в браузере не видны вовсе, этап 6 плана plan/done/ai-debug)
+// иначе его события в браузере не видны вовсе)
 socketMethods[PS_CONSOLE] = data => {
   console.log(`${DEBUG_PREFIX}[host]`, data);
 };
@@ -1197,6 +1249,20 @@ function runModules(data) {
 
   modules.vote = new VoteCtrl(voteModel, voteView);
 
+  //==========================================//
+  // Voice Module (голосовая связь)
+  //==========================================//
+
+  if (voiceConfig?.enabled) {
+    const voiceModel = new VoiceModel({ texts: voiceConfig.texts });
+    const voiceView = new VoiceView(voiceModel, gameContainer);
+
+    modules.voice = new VoiceCtrl(voiceModel, voiceView);
+    modules.controls.setPushToTalk(voiceConfig.hotkey);
+    controlsModel.publisher.on('ptt', held => voiceClient?.setPttHeld(held));
+    startVoiceClient();
+  }
+
   //==========================================//
   // Подписка на события
   //==========================================//
@@ -1217,6 +1283,8 @@ function runModules(data) {
     'keyUp',
     modules.controls.remove.bind(modules.controls),
   );
+  // потеря фокуса окна отпускает связь: keyup снаружи не придёт
+  inputListener.publisher.on('blur', () => modules.controls?.releasePtt());
   inputListener.publisher.on(
     'mouseAction',
     modules.controls.resetCursorHideTimer.bind(modules.controls),
@@ -1320,6 +1388,58 @@ function sending(name, data, reliable = true) {
   supervisor?.send(JSON.stringify([name, data]), reliable);
 }
 
+// подсистема голоса — отдельный чанк: игре без связи и standalone он не нужен
+function startVoiceClient() {
+  const session = ++voiceSession;
+
+  import('./voice/VoiceClient.js')
+    .then(async ({ default: VoiceClient }) => {
+      const client = new VoiceClient({
+        config: voiceConfig,
+        sendFloor: payload => sending(PC_VOICE_FLOOR, payload),
+        sendAudio: bytes => supervisor?.sendVoice(bytes),
+        soundManager,
+        localPlayer,
+        hud: modules.voice,
+        voiceStore: voice.store,
+        // стиль связи — хуки игры: звуки сигналов и окраска речи; старый
+        // плагин их не имеет — нейтральные тоны, чистый голос
+        voiceSounds: clientPlugin.hooks.voiceSounds,
+        voiceFilter: clientPlugin.hooks.voiceFilter,
+        diagnostics,
+      });
+
+      try {
+        await client.init();
+      } catch (error) {
+        // недособранный клиент освобождает то, что успел создать; сбой
+        // уборки не подменяет первопричину
+        try {
+          client.destroy();
+        } catch {
+          // клиент собран не до конца
+        }
+
+        throw error;
+      }
+
+      // матч закрылся, пока грузился чанк: клиент не нужен
+      if (session !== voiceSession) {
+        client.destroy();
+        return;
+      }
+
+      voiceClient = client;
+    })
+    .catch(error => {
+      diagnostics.capture(error, { source: 'voice' });
+
+      if (session === voiceSession) {
+        modules.voice?.showOwn('error', { textKey: 'unavailable' });
+      }
+    });
+}
+
 // отправка сообщения чата хосту (точка перехвата команд, адресованных
 // мастеру, а не хосту)
 function handleChatSend(message) {
@@ -1380,6 +1500,8 @@ function handleVisibilityChange() {
   // если вкладка неактивна, выключение звука
   if (document.visibilityState === 'hidden') {
     hiddenAt = performance.now();
+    // скрытая вкладка не получит keyup
+    modules.controls?.releasePtt();
     soundManager.mute();
     // иначе включение звука при возвращении (кроме паузы переподключения и
     // смены хоста — его включит возобновление сессии)
@@ -1577,6 +1699,13 @@ function handleDisconnect(closeCode) {
   lastMapData = null;
 
   document.removeEventListener('visibilitychange', handleVisibilityChange);
+  // строго до soundManager.destroy(): Howler.unload() закрывает контекст, на
+  // котором сидят захват и воспроизведение связи
+  voiceSession += 1;
+  voiceClient?.destroy();
+  voiceClient = null;
+  voice.store.clear();
+  modules.voice?.destroy();
   soundManager.destroy();
   modules.controls?.disableKeys();
 
@@ -1670,6 +1799,7 @@ function startSession(transport, reconnect = null) {
     onTerminal: handleDisconnect,
     onStateChange: handleSessionState,
     onResumed: handleSessionResumed,
+    onVoice: bytes => voiceClient?.handleAudio(bytes),
     onResumeRejected: handleResumeRejected,
     onHostLost: reportHostUnreachable,
     onColdRestart: handleColdRestart,
@@ -1713,6 +1843,8 @@ function isSessionPaused() {
 function handleSessionState(state, prev) {
   if (state === SESSION_STATES.migrating) {
     showSessionOverlay('Switching host…');
+    voiceClient?.suspend();
+    voice.store.clear();
     modules.controls?.disableKeys();
     soundManager.mute();
   } else if (state === SESSION_STATES.reconnecting) {
@@ -1721,6 +1853,8 @@ function handleSessionState(state, prev) {
       showSessionOverlay('Reconnecting…');
     }
 
+    voiceClient?.suspend();
+    voice.store.clear();
     modules.controls?.disableKeys();
     soundManager.mute();
   } else if (state === SESSION_STATES.inGame) {
@@ -2478,7 +2612,7 @@ function initLobby() {
   // сам, по нику из VIMP_ADMIN_NICKS
   games.setAdmin(lobbyAuthModel.getRole() === 'admin');
 
-  // журнал клиентских ошибок (plan/client-reports, этап 5): кнопку «Errors»
+  // журнал клиентских ошибок: кнопку «Errors»
   // видит только админ; фильтр по игре — каталог вкладки
   const clientReportsModel = new ClientReportsModel(
     lobbyConfig.clientReports,

package/src/client/network/HiddenHostHealthLog.js

@@ -7,8 +7,14 @@
 // Эпизод закрывается возвратом видимости, потерей роли хоста или
 // выгрузкой страницы (flush). Следующие эпизоды той же сессии журнал
 // склеивает с первым: растёт счётчик, details остаются первого — осознанно.
-// Эпизод без единой метрики (матч стоял, скрытие короче окна цикла) не
-// пишется. Без DOM: видимость сообщает владелец.
+// Пишется только эпизод, в котором матч просел (потеряно время или частота
+// ниже порога), это задело удалённых игроков (peers > 0), а передача хоста
+// не началась без видимой причины (handoff 'unexplained'): просадка без
+// игроков, ожидаемый отказ (нет преемника, срок роли, кулдаун, выключено) и
+// начатая передача — штатный троттлинг, а сводка здорового эпизода заняла бы
+// место details первой записи. Эпизод без единой метрики (матч стоял,
+// скрытие короче окна цикла) не пишется. Без DOM: видимость и исход
+// передачи сообщает владелец.
 
 export const HIDDEN_HEALTH_CODE = 'engine.host.hiddenHealth';
 
@@ -16,11 +22,22 @@ export default class HiddenHostHealthLog {
   /**
    * @param {Object} options
    * @param {Function} options.warn - (code, summary) запись в журнал.
+   * @param {number} options.minHealthyTickRate - ниже — эпизод просел.
+   * @param {Function} options.handoffOutcome - () => исход автопередачи
+   *   (HostHealthPolicy.hiddenHandoff).
    * @param {boolean} [options.hidden] - вкладка скрыта в момент создания.
    * @param {Function} [options.now] - монотонные часы, мс.
    */
-  constructor({ warn, hidden = false, now = () => performance.now() }) {
+  constructor({
+    warn,
+    minHealthyTickRate,
+    handoffOutcome,
+    hidden = false,
+    now = () => performance.now(),
+  }) {
     this._warn = warn;
+    this._minHealthyTickRate = minHealthyTickRate;
+    this._handoffOutcome = handoffOutcome;
     this._now = now;
     this._episode = null;
 
@@ -35,6 +52,7 @@ export default class HiddenHostHealthLog {
         minTickRate: Infinity,
         maxGapMs: 0,
         lostMs: 0,
+        peers: 0,
       };
     } else if (!hidden) {
       this.flush();
@@ -53,6 +71,11 @@ export default class HiddenHostHealthLog {
     episode.minTickRate = Math.min(episode.minTickRate, health.tickRate);
     episode.maxGapMs = Math.max(episode.maxGapMs, health.maxGapMs);
     episode.lostMs += health.lostMs;
+
+    // peers — по просевшим метрикам: сколько игроков задела просадка
+    if (health.lostMs > 0 || health.tickRate < this._minHealthyTickRate) {
+      episode.peers = Math.max(episode.peers, health.peerCount ?? 0);
+    }
   }
 
   // закрыть эпизод (если идёт) и записать сводку
@@ -65,12 +88,26 @@ export default class HiddenHostHealthLog {
       return;
     }
 
+    // peers считается по просевшим метрикам: 0 — здоровый эпизод либо
+    // просадка без удалённых игроков
+    if (episode.peers === 0) {
+      return;
+    }
+
+    const handoff = this._handoffOutcome();
+
+    if (handoff !== 'unexplained') {
+      return;
+    }
+
     this._warn(HIDDEN_HEALTH_CODE, {
       hiddenMs: Math.round(this._now() - episode.startedAt),
       samples: episode.samples,
       minTickRate: episode.minTickRate,
       maxGapMs: episode.maxGapMs,
       lostMs: episode.lostMs,
+      peers: episode.peers,
+      handoff,
     });
   }
 }

package/src/client/network/HostConnectionManager.js

@@ -1,10 +1,12 @@
 // WebRTC-answerer браузерного хоста (Фаза 2 Этапа 4). Зеркало WebRtcManager:
-// клиент — offerer (создаёт каналы meta/state и оффер), хост здесь — answerer.
+// клиент — offerer (создаёт каналы meta/state/voice и оффер), хост здесь — answerer.
 // Живёт в главном потоке (RTCPeerConnection в Worker'е недоступны); входящие
 // кадры каналов уходят в Worker через HostController, исходящие Worker-кадры
 // раскладываются по каналам meta (reliable) / state (unreliable) по флагу
 // reliable из ядра (body_has_events). Медленным пирам state-кадры дропаются
-// по bufferedAmount (бэкпрешер) — meta не дропается никогда.
+// по bufferedAmount (бэкпрешер) — meta не дропается никогда. Канал voice в
+// готовность не входит и в Worker не ходит: пакеты голоса идут ретранслятору
+// HostController.
 export default class HostConnectionManager {
   /**
    * @param {SignalingClient} signaling - сигнальный WS мастера.
@@ -26,7 +28,7 @@ export default class HostConnectionManager {
     this._threshold = opts.backpressureThreshold ?? 262144; // 256 КБ
     this._onPeersChange = opts.onPeersChange;
 
-    // clientId → { pc, meta, state, openCount, memberId }
+    // clientId → { pc, meta, state, voice, openCount, memberId }
     this._peers = new Map();
 
     signaling.publisher.on('webrtc_offer', 'onOffer', this);
@@ -59,6 +61,7 @@ export default class HostConnectionManager {
       pc,
       meta: null,
       state: null,
+      voice: null,
       openCount: 0,
       memberId,
       resume,
@@ -122,11 +125,21 @@ export default class HostConnectionManager {
   }
 
   _wireChannel(clientId, peer, channel) {
+    if (channel.label === 'voice') {
+      this._wireVoiceChannel(clientId, peer, channel);
+      return;
+    }
+
+    // чужая метка — не наш канал: ни обработчиков, ни счёта готовности
+    if (channel.label !== 'meta' && channel.label !== 'state') {
+      return;
+    }
+
     channel.binaryType = 'arraybuffer';
 
     if (channel.label === 'meta') {
       peer.meta = channel;
-    } else if (channel.label === 'state') {
+    } else {
       peer.state = channel;
     }
 
@@ -159,6 +172,34 @@ export default class HostConnectionManager {
     };
   }
 
+  _wireVoiceChannel(clientId, peer, channel) {
+    channel.binaryType = 'arraybuffer';
+    peer.voice = channel;
+
+    // голос — только ретранслятору главного потока; в Worker он не уходит
+    // никогда
+    channel.onmessage = event =>
+      this._controller.voiceIngress(clientId, event.data);
+
+    channel.onopen = () => {
+      if (this._peers.get(clientId) !== peer) {
+        return;
+      }
+
+      this._controller.attachVoice(clientId, {
+        send: bytes => {
+          if (channel.readyState === 'open') {
+            channel.send(bytes);
+          }
+        },
+        bufferedAmount: () => channel.bufferedAmount,
+      });
+    };
+
+    // потеря одного канала голоса — не повод рвать матч
+    channel.onclose = () => this._controller.detachVoice(clientId);
+  }
+
   // раскладывает исходящий Worker-кадр по каналам meta/state
   _deliver(peer, payload, reliable) {
     // JSON-протокол и событийные кадры — надёжно по meta; позиционные кадры
@@ -189,7 +230,7 @@ export default class HostConnectionManager {
     this._controller.disconnect(clientId); // Worker: removeUser
 
     // снять обработчики каналов — замыкания не должны удерживать peer
-    for (const channel of [peer.meta, peer.state]) {
+    for (const channel of [peer.meta, peer.state, peer.voice]) {
       if (channel) {
         channel.onopen = null;
         channel.onmessage = null;

package/src/client/network/HostController.js

@@ -1,3 +1,5 @@
+import VoiceRelay from '../../lib/VoiceRelay.js';
+
 // Мост главного потока между Worker'ом хоста (авторитетная симуляция) и
 // транспортами клиентов. Worker не имеет доступа к RTCPeerConnection — главный
 // поток роутит пакеты: исходящие кадры Worker'а (to_client) → нужному клиенту,
@@ -9,6 +11,9 @@
 // версию кода без разрыва P2P — старый Worker отдаёт handoff-состояние на
 // границе раунда, новый поднимается с ним, клиенты переподключаются
 // внутренними connect'ами (WebRTC-каналы живут здесь и не трогаются).
+//
+// Здесь же живёт ретранслятор голоса (VoiceRelay): пакеты голоса в Worker не
+// уходят, маршруты ему присылает мета-модуль Voice сообщением voice_route.
 
 // предохранитель от зависшего init нового Worker'а: не дождались ready —
 // своп отменяется, комната продолжает жить на старом Worker'е
@@ -56,7 +61,7 @@ export default class HostController {
    * @param {Function} [opts.onLobbyInfoChange] - смена строки карточки
    *   комнаты в лобби (string|null) — для актуализации info у мастера.
    * @param {Object} [opts.diagnostics] - журнал клиентских ошибок
-   *   (lib/diagnostics.js, plan/client-reports): туда уходят ошибки Worker'а.
+   *   (lib/diagnostics.js): туда уходят ошибки Worker'а.
    * @param {Uint8Array} [opts.checkpoint] - сжатая контрольная точка
    *   (host-migration этап 5): Worker поднимает матч из неё на паузе, старт —
    *   startAfterRestore(). Буфер передаётся списком переноса — после
@@ -102,6 +107,8 @@ export default class HostController {
 
     this._swap = null; // состояние эстафеты (Этап 5.2)
 
+    this._voiceRelay = new VoiceRelay();
+
     // ожидание границы раунда плановой передачей (host-migration этап 8d)
     this._roundBoundaryCallback = null;
 
@@ -114,7 +121,7 @@ export default class HostController {
     // подписчики метрик здоровья хоста (host-migration этап 9a)
     this._healthListeners = new Set();
 
-    // отладочные запросы в Worker (этап 6 плана plan/done/ai-debug):
+    // отладочные запросы в Worker:
     // requestId → { resolve, reject }
     this._debugRequests = new Map();
     this._debugRequestId = 0;
@@ -149,7 +156,7 @@ export default class HostController {
         });
   }
 
-  // журнал клиентских ошибок (plan/client-reports): неперехваченная ошибка
+  // журнал клиентских ошибок: неперехваченная ошибка
   // Worker'а приходит сюда. preventDefault не зовётся — консольный вывод
   // браузера остаётся как есть
   _watchWorkerErrors(worker) {
@@ -202,8 +209,36 @@ export default class HostController {
     this._worker.postMessage(msg);
   }
 
+  /**
+   * Выход голоса к соединению (WebRTC-канал гостя или loopback хоста-игрока).
+   * @param {string} socketId
+   * @param {{ send: Function, bufferedAmount?: Function }} sink
+   */
+  attachVoice(socketId, sink) {
+    this._voiceRelay.attach(socketId, sink);
+  }
+
+  /**
+   * Отцепляет выход голоса (канал voice закрылся при живом соединении).
+   * @param {string} socketId
+   */
+  detachVoice(socketId) {
+    this._voiceRelay.detach(socketId);
+  }
+
+  /**
+   * Пакет голоса от соединения: Worker его не видит.
+   * @param {string} socketId
+   * @param {ArrayBuffer|Uint8Array} data
+   */
+  voiceIngress(socketId, data) {
+    this._voiceRelay.ingress(socketId, data);
+  }
+
   // отключает клиента
   disconnect(socketId) {
+    // ретранслятор живёт в главном потоке: ждать паузу эстафеты ему нечего
+    this._voiceRelay.detach(socketId);
     this._deliveries.delete(socketId);
 
     const msg = { type: 'disconnect', socketId };
@@ -456,7 +491,7 @@ export default class HostController {
   }
 
   /**
-   * Отладочный контур (этап 6 плана plan/done/ai-debug): начинает запись живого
+   * Отладочный контур: начинает запись живого
    * матча в формат сценария headless-runner'а.
    * @returns {Promise<boolean>} false — dev-режим в комнате выключен.
    */
@@ -580,6 +615,7 @@ export default class HostController {
     this._shutdownResolve?.();
 
     this._rejectDebugRequests('host destroyed');
+    this._voiceRelay.clear();
 
     if (this._swap) {
       const { reject } = this._swap;
@@ -705,6 +741,9 @@ export default class HostController {
       this._postCheckpointState(next);
     }
 
+    // маршруты старого Worker'а мертвы (новый начинает без эфиров); выходы
+    // остаются — каналы WebRTC эстафету переживают
+    this._voiceRelay.clear();
     this._worker.terminate();
     this._worker = next;
     this._worker.onmessage = e => this._onWorkerMessage(e.data);
@@ -761,6 +800,10 @@ export default class HostController {
         this._reportWorkerMessage(msg, msg.kind);
         break;
 
+      case 'voice_route':
+        this._voiceRelay.applyRoute(msg);
+        break;
+
       case 'map_changed':
         this._onMapChange?.(msg.mapName);
         break;