vimp-engine 0.38.2 → 0.39.0

package/src/lib/VoiceRelay.js

@@ -0,0 +1,200 @@
+import wsports from '../config/wsports.js';
+import {
+  VOICE_BACKPRESSURE_BYTES,
+  VOICE_RELAY_BYTE_RATE,
+  VOICE_RELAY_RATE,
+} from '../config/voiceProtocol.js';
+import { readVoiceHeader, stampForListeners, toBytes } from './voicePacket.js';
+
+// Ретранслятор голоса транспортного уровня (главный поток вкладки хоста).
+// Раздаёт пакеты говорящего слушателям по маршруту, который присылает мета-
+// модуль Voice. Аудио не входит в Worker, порт-машину и ядро. Содержимое
+// пакетов не логируется.
+
+// пополнение ведра: не выше ёмкости burst
+const refill = (value, burst, perSecond, elapsed) =>
+  Math.min(burst, value + elapsed * perSecond);
+
+export default class VoiceRelay {
+  /**
+   * @param {Object} [opts]
+   * @param {Function} [opts.now] - мс; по умолчанию performance.now().
+   * @param {{ packetsPerSecond: number, burst: number }} [opts.rate]
+   * @param {{ bytesPerSecond: number, burst: number }} [opts.byteRate]
+   * @param {number} [opts.backpressureBytes] - порог bufferedAmount выхода.
+   */
+  constructor({
+    now = () => globalThis.performance.now(),
+    rate = VOICE_RELAY_RATE,
+    byteRate = VOICE_RELAY_BYTE_RATE,
+    backpressureBytes = VOICE_BACKPRESSURE_BYTES,
+  } = {}) {
+    this._now = now;
+    this._rate = rate;
+    this._byteRate = byteRate;
+    this._backpressureBytes = backpressureBytes;
+
+    // socketId → { send(bytes), bufferedAmount?() }
+    this._sinks = new Map();
+    // speakerSocketId → { talkId, speakerGameId, listenerSocketIds }
+    this._routes = new Map();
+    // speakerSocketId → { tokens, bytes, last }
+    this._buckets = new Map();
+  }
+
+  /**
+   * Выход к соединению (канал WebRTC гостя или loopback хоста-игрока).
+   * @param {string} socketId
+   * @param {{ send: Function, bufferedAmount?: Function }} sink
+   */
+  attach(socketId, sink) {
+    this._sinks.set(socketId, sink);
+  }
+
+  /**
+   * Соединение ушло: снимает выход, маршрут, где оно говорящий, и убирает его
+   * из списков слушателей.
+   * @param {string} socketId
+   */
+  detach(socketId) {
+    this._sinks.delete(socketId);
+    this._routes.delete(socketId);
+    this._buckets.delete(socketId);
+
+    for (const [speakerSocketId, route] of this._routes) {
+      if (route.listenerSocketIds.includes(socketId)) {
+        this._routes.set(speakerSocketId, {
+          ...route,
+          listenerSocketIds: route.listenerSocketIds.filter(
+            id => id !== socketId,
+          ),
+        });
+      }
+    }
+  }
+
+  /**
+   * Маршрут от модуля Voice; route === null снимает его.
+   * @param {Object} msg
+   * @param {string} msg.speakerSocketId
+   * @param {{ talkId: number, speakerGameId: number,
+   *   listenerSocketIds: string[] }|null} msg.route
+   */
+  applyRoute({ speakerSocketId, route }) {
+    if (!route) {
+      this._routes.delete(speakerSocketId);
+      this._buckets.delete(speakerSocketId);
+      return;
+    }
+
+    // ведро полное только у нового эфира
+    if (this._routes.get(speakerSocketId)?.talkId !== route.talkId) {
+      this._buckets.set(speakerSocketId, {
+        tokens: this._rate.burst,
+        bytes: this._byteRate.burst,
+        last: this._now(),
+      });
+    }
+
+    this._routes.set(speakerSocketId, {
+      talkId: route.talkId,
+      speakerGameId: route.speakerGameId,
+      listenerSocketIds: [...route.listenerSocketIds],
+    });
+  }
+
+  /**
+   * Пакет от соединения socketId. Любой провал проверок — молчаливый выброс.
+   * @param {string} socketId
+   * @param {ArrayBuffer|Uint8Array} data
+   */
+  ingress(socketId, data) {
+    const route = this._routes.get(socketId);
+
+    if (!route) {
+      return;
+    }
+
+    const bytes = toBytes(data);
+    const header = readVoiceHeader(bytes);
+
+    if (
+      !header ||
+      header.port !== wsports.client.VOICE_AUDIO ||
+      header.talkId !== route.talkId ||
+      !this._admit(socketId, bytes.length)
+    ) {
+      return;
+    }
+
+    // id говорящего хост знает сам — клиентскому байту не верим
+    stampForListeners(bytes, route.speakerGameId);
+
+    for (const id of route.listenerSocketIds) {
+      const sink = this._sinks.get(id);
+
+      if (!sink) {
+        continue;
+      }
+
+      // сбой одного выхода не лишает пакета остальных слушателей
+      try {
+        // живой голос важнее старого: переполненному выходу пакет не шлём
+        if (sink.bufferedAmount?.() > this._backpressureBytes) {
+          continue;
+        }
+
+        sink.send(bytes);
+      } catch {
+        // канал закрывается: пакет пропадает, как при потере
+      }
+    }
+  }
+
+  /**
+   * Снимает все маршруты и вёдра (эстафета Worker'ов, закрытие комнаты).
+   * Выходы остаются: транспорты переживают смену Worker'а.
+   */
+  clear() {
+    this._routes.clear();
+    this._buckets.clear();
+  }
+
+  // вёдра говорящего: пакеты (packetsPerSecond, ёмкость burst) и байты
+  // (bytesPerSecond, ёмкость burst). Пакет проходит, только если хватает
+  // обоих; отказ не тратит ни одного
+  _admit(socketId, size) {
+    const bucket = this._buckets.get(socketId);
+    const now = this._now();
+
+    if (!bucket) {
+      return false;
+    }
+
+    const elapsed = (now - bucket.last) / 1000;
+
+    bucket.tokens = refill(
+      bucket.tokens,
+      this._rate.burst,
+      this._rate.packetsPerSecond,
+      elapsed,
+    );
+    bucket.bytes = refill(
+      bucket.bytes,
+      this._byteRate.burst,
+      this._byteRate.bytesPerSecond,
+      elapsed,
+    );
+    bucket.last = now;
+
+    // отрицание «>=», а не «<»: NaN в ведре закрывает, а не открывает
+    if (!(bucket.tokens >= 1 && bucket.bytes >= size)) {
+      return false;
+    }
+
+    bucket.tokens -= 1;
+    bucket.bytes -= size;
+
+    return true;
+  }
+}

package/src/lib/applyRoomOverrides.js

@@ -54,7 +54,7 @@ export function applyRoomOverrides(
     game.timers.mapTime = clampTime(room.mapTime);
   }
 
-  // dev-режим вкладки хоста (этап 6 плана plan/done/ai-debug): включает рекордер
+  // dev-режим вкладки хоста: включает рекордер
   // и хостовый CONSOLE-лог. Прод-бандл его не выставляет — поведение то же
   if (typeof room.isDevMode === 'boolean') {
     game.isDevMode = room.isDevMode;

package/src/lib/buildClientConfig.js

@@ -1,3 +1,5 @@
+import { normalizeVoiceConfig } from './voiceConfig.js';
+
 // Сборка клиентского CONFIG_DATA (порт 0): merge движковых дефолтов
 // (src/config/clientDefaults.js) с игровым client-конфигом
 // (@vimp-games/tanks/config/client.js) + время голосования и данные client-side
@@ -54,5 +56,10 @@ export const buildClientConfig = (game, defaults, gameClient) => {
   // читает hot-буфер — бандл клиента не обязан совпадать с бандлом хоста
   config.snapshot = game.snapshot;
 
+  // голосовая связь: клиенту нужен весь блок — хоткей, тайминги для HUD и
+  // локальных таймеров, битрейт энкодера и подписи. enabled здесь уже
+  // фактический (createHostRuntime гасит его без ретранслятора)
+  config.voice = game.voice ?? normalizeVoiceConfig(undefined);
+
   return config;
 };

package/src/lib/capabilities.js

@@ -43,7 +43,7 @@ export const ENGINE_CAPABILITIES = createRegistry('engine-capabilities', [
   // `SimCtx::map_body_state`) и доступ игры к телам карты по индексу
   // (хэндл, индекс по хэндлу, отключение тела)
   { value: 'map.bodyState', since: '0.34.0' },
-  // сервис пула `diagnostics` (журнал клиентских ошибок, plan/client-reports);
+  // сервис пула `diagnostics` (журнал клиентских ошибок);
   // опционален — игра не пишет его в `requires`
   { value: 'diagnostics', since: '0.35.0' },
   // контрольная точка хоста посреди раунда (host-migration этап 5):
@@ -51,6 +51,10 @@ export const ENGINE_CAPABILITIES = createRegistry('engine-capabilities', [
   // Писать в `requires` не нужно: старый движок флаг просто игнорирует, и
   // игра на нём мигрирует мягко
   { value: 'host.migration', since: '0.36.0' },
+  // голосовая связь (gameConfig.voice, порты VOICE_*, сервис пула `voice`,
+  // хуки `hooks.voiceSounds`/`hooks.voiceFilter`); опциональна — игра не
+  // пишет её в `requires`
+  { value: 'voice', since: '0.39.0' },
 ]);
 
 // плоский список имён — то, чем правило контракта B2 проверяет `requires`

package/src/lib/checkpointCodec.js

@@ -4,8 +4,7 @@
 //
 // Контейнер до сжатия: [u32 metaLen LE][meta JSON utf-8][байты дампа ядра];
 // весь буфер — gzip. Дамп ядра сам по себе JSON (serialize_state), и без
-// сжатия точка tanks весит ~420 КБ, с ним ~21 КБ (plan/host-migration,
-// spike-results).
+// сжатия точка tanks весит ~420 КБ, с ним ~21 КБ.
 
 import hostDefaults from '../config/hostDefaults.js';
 

package/src/lib/coreConfig.js

@@ -2,7 +2,7 @@ import { SNAPSHOT_FORMAT_VERSION } from '../config/opcodes.js';
 import hostDefaults from '../config/hostDefaults.js';
 import wsports from '../config/wsports.js';
 
-// Сборка JSON-конфига Rust-ядра (packages/engine/core + core/ в репозитории
+// Сборка JSON-конфига Rust-ядра (крейт vimp-engine-core + core/ в репозитории
 // игры, например vimp-tanks): движковая половина
 // (timeStep/mapScale/mapSetId/snapshot/seed) + игровая
 // (models/weapons/playerKeys/panel/friendlyFire) — форма {engine, game} из

package/src/lib/createHostRuntime.js

@@ -29,6 +29,9 @@ import HostGame from '../host/HostGame.js';
  * @param {Function} [options.overrideGameConfig] - Правка собранного конфига
  *   игры перед созданием ядра; в проде не задаётся, нужна отладочному
  *   прогону (сценарий подкручивает networkSendRate и таймеры).
+ * @param {boolean} [options.voiceRelay] - У контура есть ретранслятор голоса
+ *   на транспортном уровне (браузерный хост лобби); без него связь
+ *   выключается, даже если игра её объявила (standalone, headless, dedicated).
  * @returns {Promise<Object>} { hostPlugin, game, seed, core, clientCfg,
  *   socketManager, host }.
  */
@@ -38,6 +41,7 @@ export async function createHostRuntime(room, options = {}) {
     createSocketManager = defaultCreateSocketManager,
     hostOptions = {},
     overrideGameConfig = null,
+    voiceRelay = false,
   } = options;
 
   const hostPlugin = await loadHostPlugin(room);
@@ -52,6 +56,10 @@ export async function createHostRuntime(room, options = {}) {
     overrideGameConfig(game);
   }
 
+  if (!voiceRelay && game.voice?.enabled) {
+    game.voice = Object.freeze({ ...game.voice, enabled: false });
+  }
+
   // seed уезжает наружу вызывающему: без него прогон матча невоспроизводим
   // (реплей задаёт room.seed и получает тот же мир)
   const seed =
@@ -87,7 +95,7 @@ export async function createHostRuntime(room, options = {}) {
     // преемник собирает из них тот же конфиг ядра
     roomSettings: pickRoomSettings(room),
     mapsVersion: room?.mapsVersion ?? null,
-    // рекордер (этап 6 плана plan/done/ai-debug) кладёт seed в сценарий — без него
+    // рекордер кладёт seed в сценарий — без него
     // записанный матч невоспроизводим
     seed,
     ...hostOptions,

package/src/lib/gameConfigView.js

@@ -1,4 +1,6 @@
 import hostDefaults from '../config/hostDefaults.js';
+import { VOICE_CONFIG_PATHS } from '../config/voiceDefaults.js';
+import { normalizeVoiceConfig } from './voiceConfig.js';
 
 // Единственная точка чтения HostPlugin.gameConfig движком (этап 2 плана
 // plugin-forward-compat). До неё движок разыменовывал конфиг игры россыпью
@@ -77,7 +79,11 @@ const FIELDS = {
 // те, за которые он подставляет умолчание. Раздел слепка поверхности
 // (contract/surface.json → gameConfigFields): исчезнувший отсюда путь —
 // нарушение И1, потому что игра могла его написать.
-export const KNOWN_GAME_CONFIG_PATHS = Object.keys(FIELDS);
+// Пути связи живут в config/voiceDefaults.js.
+export const KNOWN_GAME_CONFIG_PATHS = [
+  ...Object.keys(FIELDS),
+  ...VOICE_CONFIG_PATHS,
+];
 
 // ЗАМОРОЖЕНО (И2). Этот список может только СОКРАЩАТЬСЯ.
 // Добавление сюда отвергнет все ранее опубликованные игры — вместо этого
@@ -182,6 +188,10 @@ export function createGameConfigView(gameConfig, gameId = 'unknown') {
     );
   }
 
+  // блок связи нормализуется целиком (а не по путям FIELDS): неверное
+  // значение тоже должно получить дефолт, а не только отсутствующее
+  view.voice = normalizeVoiceConfig(source.voice, { gameId });
+
   assertConsistent(view, source, gameId);
 
   return Object.freeze(view);

package/src/lib/gameId.js

@@ -1,6 +1,6 @@
 // Формат id игры — изоморфно: его проверяет мастер (реестр, раздача, каталог)
 // и клиентский роутер ссылок (client/lib/roomLink.js) до похода в сеть.
-// Значение обязано совпадать с packages/auth/src/config/auth.js:games
+// Значение обязано совпадать с games из конфига auth-сервиса
 // (см. master/gameRefs.js — он реэкспортирует отсюда)
 export const GAME_ID_PATTERN = /^[a-z][a-z0-9-]{1,30}$/;
 

package/src/lib/gamePlugin.js

@@ -7,8 +7,12 @@ import { createGameConfigView } from './gameConfigView.js';
 // entries.client из манифеста.
 
 // каталог всех игр мастера (GameCatalog, см. Этап 6.2) — массив манифестов
-export async function fetchGamesManifest(url = '/games/manifest.json') {
-  const res = await fetch(url);
+// doFetch подставляет клиент: загрузка страницы повторяет сбой сети
+export async function fetchGamesManifest(
+  url = '/games/manifest.json',
+  doFetch = fetch,
+) {
+  const res = await doFetch(url);
 
   if (!res.ok) {
     throw new Error(`games manifest: HTTP ${res.status}`);

package/src/lib/jwt.js

@@ -41,7 +41,7 @@ export function decodeJwtPayload(token) {
 }
 
 // Авторитетная проверка identity-токена (Этап B3): подпись RS256 по JWKS
-// central auth-сервиса (packages/auth), issuer и срок годности. Работает через
+// central auth-сервиса, issuer и срок годности. Работает через
 // Web Crypto API (crypto.subtle) — доступен в браузере, Worker'е хоста и в
 // Node ≥19 глобально, отдельной JWT-библиотеки не требует. Возвращает
 // проверенный payload ({ sub, nick, iss, exp, ... }) или бросает исключение.

package/src/lib/packageLink.js

@@ -1,63 +1,31 @@
-// Ссылка на проект для футеров лобби и формы входа: движок показывает рядом
-// npm-версию, и клик по соседней ячейке ведёт на страницу проекта этого пакета.
+// Адрес проекта пакета — его `repository`: ссылка ведёт на саму игру, в том
+// числе закрытую. `homepage` не читается. Фолбэка нет: пакет без repository
+// адреса не получает — страница пакета в npm маскировала бы недостающие
+// метаданные. О пропущенном поле предупреждает правило контракта A7.
 //
-// Источник — `homepage` его package.json (иначе `repository`). Фолбэка нет:
-// пакет, не объявивший ни того, ни другого, ссылки не получает, и ячейка
-// футера остаётся пустой. Это сознательно — прежний фолбэк на страницу пакета
-// в npm давал разнобой («GitHub» у одной игры, «npm» у другой) и молча
-// маскировал недостающие метаданные вместо того, чтобы показать их отсутствие.
-// О пропущенном поле предупреждает правило контракта A7.
-//
-// Хостинг не ограничен github.com: подпись выводится из хоста, поэтому чужой
-// плагин на GitLab получает честную ссылку, а не пустую ячейку.
-//
-// Модуль изоморфный: мастер зовёт resolveProjectUrl для пакета игры
-// (GameCatalog), клиент — для собственного package.json движка
-// (client/lib/engineVersion.js).
+// Хостинг не ограничен github.com. Модуль изоморфный: мастер зовёт
+// resolveProjectUrl для метаданных пакета игры (адрес уходит в реестр игр),
+// devtools — для package.json игры (правило A7).
 
 /**
- * Адрес проекта из package.json, приведённый к https: homepage, иначе
- * repository.
+ * Адрес проекта из package.json, приведённый к http(s): поле repository.
  * @param {Object} pkg - разобранный package.json
- * @returns {string|null} https-URL либо null, если поля нет или это не адрес
+ * @returns {string|null} http(s)-URL либо null, если поля нет или это не адрес
  */
 export function resolveProjectUrl(pkg) {
   if (!pkg || typeof pkg !== 'object') {
     return null;
   }
 
-  const { homepage, repository } = pkg;
+  const { repository } = pkg;
 
   // repository бывает и строкой ("github:user/repo"), и объектом {type, url}
-  const declared =
-    typeof repository === 'string' ? repository : repository?.url;
-
-  // homepage важнее repository: поле repository обязано называть
-  // репозиторий публикации (его сверяет npm Trusted Publishing), и у пакета
-  // из закрытого репозитория такая ссылка отдаёт игроку 404
-  return normalize(homepage) ?? normalizeRepository(declared);
-}
-
-/**
- * Ссылка футера по готовому адресу проекта.
- * @param {string|null} [url] - результат resolveProjectUrl
- * @returns {{url: string, label: string}|null} null, если адреса нет
- */
-export function projectLink(url) {
-  // адрес перепроверяется, хотя свои вызовы приходят уже из
-  // resolveProjectUrl: функция — публичный экспорт ("./lib/*"), а результат
-  // уходит прямо в href якоря (client/lib/footerLink.js)
-  const value = typeof url === 'string' ? url.trim() : '';
-
-  if (!/^https?:\/\//.test(value)) {
-    return null;
-  }
-
-  return { url: value, label: labelFor(value) };
+  return normalizeRepository(
+    typeof repository === 'string' ? repository : repository?.url,
+  );
 }
 
-// шорткат "user/repo" — семантика поля repository (так его читает npm), в
-// homepage такая строка означала бы относительный путь, а не адрес на GitHub
+// шорткат "user/repo" — семантика поля repository (так его читает npm)
 function normalizeRepository(raw) {
   const value = typeof raw === 'string' ? raw.trim() : '';
 
@@ -94,6 +62,9 @@ function normalize(raw) {
 
   url = url.replace(/^git\+/, '');
 
+  // порт SSH (ssh://host:2222/…) к адресу https не относится
+  url = url.replace(/^(ssh:\/\/(?:[^/@]*@)?[^/:@]+):\d+(?=\/|$)/, '$1');
+
   // scp-форма git@host:user/repo (в том числе с лишним ssh://, как её
   // нередко пишет npm) — двоеточие здесь разделитель, не порт
   const scp = /^(?:ssh:\/\/)?git@([^:/]+):(.+)$/.exec(url);
@@ -117,22 +88,8 @@ function normalize(raw) {
       // в href он уехал бы в DOM и историю браузера
       .replace(/^(https?:\/\/)[^/@]*@/, '$1')
       .replace(/\.git(?=$|[#?])/, '')
-      // npm сам дописывает "#readme" в homepage при генерации package.json
+      // якорь #readme в адресе репозитория ссылке не нужен
       .replace(/#readme$/, '')
       .replace(/\/+$/, '')
   );
 }
-
-// подпись ячейки: у наших пакетов это всегда GitHub, у чужого хостинга —
-// его хост, чтобы подпись не врала об источнике
-function labelFor(url) {
-  let host;
-
-  try {
-    host = new URL(url).hostname.replace(/^www\./, '');
-  } catch {
-    return 'Website';
-  }
-
-  return host === 'github.com' ? 'GitHub' : host;
-}

package/src/lib/validators.js

@@ -13,7 +13,7 @@ const NAME_REGEXP = new RegExp('^[a-zA-Z]([\\w\\s#]{0,13})[\\w]{1}$');
 export const isValidName = name =>
   typeof name === 'string' && NAME_REGEXP.test(name);
 
-// ник профиля: копия правила auth-сервиса (packages/auth/src/lib/validators.js)
+// ник профиля: копия правила auth-сервиса (валидаторы auth-сервиса)
 // — общей рантайм-зависимости у пакетов нет. Строже isValidName: внутри ника
 // допустим только обычный пробел, не любой \s
 const NICK_REGEXP = new RegExp('^[a-zA-Z]([\\w #]{0,13})[\\w]{1}$');
@@ -272,8 +272,8 @@ export const clampLimit = (value, fallback, max) => {
 // на его стороне — минута (lobbyConfig.playerData.minFlushInterval), столько
 // игр в неё не влезает.
 //
-// Множитель СВЯЗАН с rank.maxPoints auth-сервиса (packages/auth/src/config/
-// auth.js): мастер не должен пропускать то, что auth отклонит. Отклонённое
+// Множитель СВЯЗАН с rank.maxPoints из конфига auth-сервиса: мастер
+// не должен пропускать то, что auth отклонит. Отклонённое
 // тело для хоста неустранимо — PlayerDataSync повторял бы его до конца жизни
 // комнаты, — поэтому при правке per-game maxGameScore проверяется и потолок
 // суммы на той стороне.

package/src/lib/voiceConfig.js

@@ -0,0 +1,136 @@
+import {
+  VOICE_DEFAULTS,
+  VOICE_HOTKEY_RANGE,
+  VOICE_KEYS,
+  VOICE_RANGES,
+  VOICE_SCOPES,
+  VOICE_TEXT_KEYS,
+  VOICE_TEXT_MAX_LENGTH,
+} from '../config/voiceDefaults.js';
+
+const isPlainObject = value =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * Разбирает блок gameConfig.voice. Конфиг не отвергается никогда: плохое
+ * значение заменяется дефолтом (числа вне диапазона — зажимом) и попадает в
+ * problems. Одна функция на два потребителя: рантайм предупреждает, правило
+ * контракта B11 отчитывается.
+ * @param {*} raw - Что написала игра (undefined/null — блока нет).
+ * @returns {{ config: Object, problems: string[] }} config — полный блок
+ *   (все ключи, вложенный texts); problems — описания на английском.
+ */
+export function inspectVoiceConfig(raw) {
+  const problems = [];
+  const config = { ...VOICE_DEFAULTS, texts: { ...VOICE_DEFAULTS.texts } };
+
+  if (raw === undefined || raw === null) {
+    return { config, problems };
+  }
+
+  if (!isPlainObject(raw)) {
+    problems.push('voice must be a plain object');
+
+    return { config, problems };
+  }
+
+  for (const key of Object.keys(raw)) {
+    if (!VOICE_KEYS.includes(key)) {
+      problems.push(`unknown key "voice.${key}"`);
+    }
+  }
+
+  if (raw.enabled !== undefined) {
+    if (typeof raw.enabled === 'boolean') {
+      config.enabled = raw.enabled;
+    } else {
+      problems.push('voice.enabled must be a boolean');
+    }
+  }
+
+  if (raw.scope !== undefined) {
+    if (VOICE_SCOPES.includes(raw.scope)) {
+      config.scope = raw.scope;
+    } else {
+      problems.push(`voice.scope must be one of ${VOICE_SCOPES.join(', ')}`);
+    }
+  }
+
+  if (raw.hotkey !== undefined) {
+    const [min, max] = VOICE_HOTKEY_RANGE;
+
+    if (
+      Number.isInteger(raw.hotkey) &&
+      raw.hotkey >= min &&
+      raw.hotkey <= max
+    ) {
+      config.hotkey = raw.hotkey;
+    } else {
+      problems.push(`voice.hotkey must be an integer keyCode ${min}..${max}`);
+    }
+  }
+
+  for (const [key, [min, max]] of Object.entries(VOICE_RANGES)) {
+    const value = raw[key];
+
+    if (value === undefined) {
+      continue;
+    }
+
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      problems.push(`voice.${key} must be a finite number`);
+    } else if (value < min || value > max) {
+      config[key] = Math.min(max, Math.max(min, value));
+      problems.push(`voice.${key} must be within ${min}..${max}, clamped`);
+    } else {
+      config[key] = value;
+    }
+  }
+
+  if (raw.texts !== undefined) {
+    if (!isPlainObject(raw.texts)) {
+      problems.push('voice.texts must be a plain object');
+    } else {
+      for (const [key, value] of Object.entries(raw.texts)) {
+        if (!VOICE_TEXT_KEYS.includes(key)) {
+          problems.push(`unknown key "voice.texts.${key}"`);
+        } else if (
+          typeof value !== 'string' ||
+          value.length > VOICE_TEXT_MAX_LENGTH
+        ) {
+          problems.push(
+            `voice.texts.${key} must be a string up to ` +
+              `${VOICE_TEXT_MAX_LENGTH} characters`,
+          );
+        } else {
+          config.texts[key] = value;
+        }
+      }
+    }
+  }
+
+  return { config, problems };
+}
+
+/**
+ * Рантайм-обёртка: каждая проблема уходит в warn.
+ * @param {*} raw - gameConfig.voice как есть.
+ * @param {Object} [options]
+ * @param {string} [options.gameId]
+ * @param {Function} [options.warn]
+ * @returns {Object} Замороженный полный блок (texts тоже заморожен).
+ */
+export function normalizeVoiceConfig(
+  raw,
+  { gameId = 'unknown', warn = console.warn } = {},
+) {
+  const { config, problems } = inspectVoiceConfig(raw);
+
+  for (const problem of problems) {
+    warn(`game "${gameId}": voice: ${problem}`);
+  }
+
+  config.texts = Object.freeze(config.texts);
+
+  return Object.freeze(config);
+}