vimp-engine 0.38.2 → 0.38.3

package/src/client/network/HostController.js

@@ -56,7 +56,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(). Буфер передаётся списком переноса — после
@@ -114,7 +114,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 +149,7 @@ export default class HostController {
         });
   }
 
-  // журнал клиентских ошибок (plan/client-reports): неперехваченная ошибка
+  // журнал клиентских ошибок: неперехваченная ошибка
   // Worker'а приходит сюда. preventDefault не зовётся — консольный вывод
   // браузера остаётся как есть
   _watchWorkerErrors(worker) {
@@ -456,7 +456,7 @@ export default class HostController {
   }
 
   /**
-   * Отладочный контур (этап 6 плана plan/done/ai-debug): начинает запись живого
+   * Отладочный контур: начинает запись живого
    * матча в формат сценария headless-runner'а.
    * @returns {Promise<boolean>} false — dev-режим в комнате выключен.
    */

package/src/client/network/HostHealthPolicy.js

@@ -56,6 +56,7 @@ export default class HostHealthPolicy {
     this._successor = false;
     this._hiddenSince = null;
     this._hiddenTimer = null;
+    this._hiddenOutcome = null;
     this._lastAutoAt = null;
     this._cooldownBefore = null;
     this._samples = [];
@@ -80,6 +81,12 @@ export default class HostHealthPolicy {
     this._successor = false;
     this._resetSamples();
 
+    // исход прошлой роли уже прочитан её журналом (flush при потере роли);
+    // новой роли он не принадлежит
+    if (isHost) {
+      this._hiddenOutcome = null;
+    }
+
     // роль получена скрытой вкладкой: скрытие отсчитывается от получения
     if (isHost && this._hiddenSince !== null) {
       this._hiddenSince = this._hostSince;
@@ -98,6 +105,7 @@ export default class HostHealthPolicy {
   setHidden(hidden) {
     if (hidden && this._hiddenSince === null) {
       this._hiddenSince = this._now();
+      this._hiddenOutcome = null;
       this._armHiddenTimer();
     } else if (!hidden) {
       this._hiddenSince = null;
@@ -105,6 +113,19 @@ export default class HostHealthPolicy {
     }
   }
 
+  /**
+   * Исход передачи для последнего эпизода скрытия (живёт до следующего
+   * скрытия или новой роли хоста, переживает возврат видимости и потерю
+   * роли — его читает журнал закрываемого эпизода): null — порог
+   * hiddenHandoffMs не достигнут; 'started' — передача началась;
+   * 'disabled' | 'no-successor' | 'blocked' (срок роли или кулдаун) —
+   * ожидаемый отказ; 'unexplained' — всё разрешено, а передача не началась.
+   * @returns {string|null}
+   */
+  hiddenHandoff() {
+    return this._hiddenOutcome;
+  }
+
   // сэмпл здоровья Worker'а
   addHealth(health) {
     if (this._hostSince === null || !health) {
@@ -182,6 +203,8 @@ export default class HostHealthPolicy {
     }
 
     if (this._handOverNow('hidden')) {
+      this._hiddenOutcome = 'started';
+
       return true;
     }
 
@@ -191,9 +214,27 @@ export default class HostHealthPolicy {
       this._armHiddenTimer(waitMs);
     }
 
+    // начатая передача исход не меняет: следующие проверки её уже не стартуют
+    if (this._hiddenOutcome !== 'started') {
+      this._hiddenOutcome = this._refusal(waitMs);
+    }
+
     return false;
   }
 
+  // почему передача со скрытой вкладки не началась
+  _refusal(waitMs) {
+    if (!this._enabled()) {
+      return 'disabled';
+    }
+
+    if (!this._successor) {
+      return 'no-successor';
+    }
+
+    return waitMs > 0 ? 'blocked' : 'unexplained';
+  }
+
   // немедленная передача: ждущую границы — ускорить, иначе начать
   _handOverNow(reason) {
     if (!this._enabled() || !this._successor) {

package/src/client/network/InlineHostBridge.js

@@ -11,7 +11,7 @@ import { createGuestIdentity } from '../../host/identity.js';
 // Почему inline, а не Worker: HostPlugin принципиально непередаваем в Worker
 // (postMessage не несёт функции), а standalone SDK получает от репозитория
 // игры именно живой объект плагина. Прод-путь (хост в Worker'е) не меняется —
-// расхождение dev/prod осознанное, см. plan/standalone-sdk/README.md.
+// расхождение dev/prod осознанное.
 //
 // Мастера в этом контуре нет: личность гостевая (ник из формы, identity.js),
 // профиль offline-заглушкой (lib/offlinePlayerData.js).
@@ -102,6 +102,13 @@ export default class InlineHostBridge {
 
     this._runtime = runtime;
 
+    // сбой чат-команды игры виден в консоли вкладки вместе с кадрами обработчика
+    runtime.host.setDiagnosticSink(report =>
+      console.error(
+        `[vimp] ${report.message}${report.stack ? `\n${report.stack}` : ''}`,
+      ),
+    );
+
     this._portMachine = new PortMachine({
       host: runtime.host,
       socketManager: runtime.socketManager,

package/src/client/session/HandoffFlow.js

@@ -261,6 +261,11 @@ export default class HandoffFlow {
     this._policy?.addHealth(health);
   }
 
+  // исход передачи для последнего эпизода скрытия (HostHealthPolicy)
+  hiddenHandoff() {
+    return this._policy?.hiddenHandoff() ?? null;
+  }
+
   // «Leave server» из меню комнаты (этап 8.3). Хост при других людях отдаёт
   // роль бете без отката и уходит; один в комнате — закрывает её
   // (host_leaving: людей нет — мастер закрывает комнату сразу). Гость

package/src/client/session/HostRole.js

@@ -321,11 +321,14 @@ export default class HostRole {
       onStats: this._debug ? stats => this._debug('standby sent', stats) : null,
     });
 
-    // метрики здоровья Worker'а (этап 9a): скрытая вкладка троттлит цикл —
-    // насколько, уходит в журнал одной сводкой за эпизод
+    // метрики здоровья Worker'а: эпизод скрытия, в котором матч просел,
+    // задел удалённых игроков, а автопередача не началась без видимой
+    // причины, уходит в журнал одной сводкой (HiddenHostHealthLog)
     this._hiddenLog = this._factories.hiddenLog({
       warn: (code, summary) =>
         this._diagnostics.warn(code, summary, { source: 'client' }),
+      minHealthyTickRate: migration.auto.overloadTickRate,
+      handoffOutcome: () => this._getHandoff().hiddenHandoff(),
       hidden: this._ui.isHidden(),
     });
     this._healthReporter = this._isLobbyMode

package/src/client/style.css

@@ -1,10 +1,9 @@
 @charset "UTF-8";
 
-/* База страницы: раньше жила инлайном в packages/engine/index.html, но в
-   репозитории игры этого файла нет — а без правил ниже интерфейс движка
-   остался бы без своей типографики и раскладки. Standalone SDK импортирует
-   этот файл целиком, поэтому всё, что здесь есть, применяется и к
-   встраивающей странице. */
+/* База страницы: типографика и раскладка интерфейса движка живут здесь, а
+   не в index.html, потому что в репозитории игры такого файла нет.
+   Standalone SDK импортирует этот файл целиком, поэтому всё, что здесь
+   есть, применяется и к встраивающей странице. */
 html,
 body {
   width: 100%;
@@ -1329,7 +1328,7 @@ body.hide-cursor {
   color: #d66;
 }
 
-/* журнал клиентских ошибок (plan/client-reports, этап 5): тот же каркас и
+/* журнал клиентских ошибок: тот же каркас и
    палитра, что у панели реестра игр; графы — .games-filters/.games-filter-btn */
 #reports-panel {
   background-color: #222;

package/src/client/views/gameShell.js

@@ -55,9 +55,9 @@ const SHELL = [
             tag: 'div',
             id: 'auth-link',
             children: [
-              // ссылка и версия пакета ИГРЫ — заполняет main.js по AUTH_DATA
-              // из метаданных пакета в манифесте
-              { tag: 'p', children: [{ tag: 'a', id: 'auth-package-link' }] },
+              // версия пакета ИГРЫ (из манифеста) и ссылка на документацию
+              // (только в dev-сборке) — заполняет main.js по AUTH_DATA
+              { tag: 'p', children: [{ tag: 'a', id: 'auth-docs-link' }] },
               { tag: 'p', id: 'auth-version' },
               { tag: 'p', text: `© ${new Date().getFullYear()} VIMP` },
             ],

package/src/client/views/includes/auth.pug

@@ -15,10 +15,10 @@ div#auth
     div#auth-informs
 
     div#auth-link
-      //- ссылка и версия пакета ИГРЫ (мастер кладёт их в манифест, читая
-      //- package.json пакета) — проставляет main.js по AUTH_DATA; без данных
-      //- ячейки остаются пустыми
+      //- версия пакета ИГРЫ (мастер кладёт её в манифест, читая package.json
+      //- пакета) и ссылка на документацию (только в dev-сборке) —
+      //- проставляет main.js по AUTH_DATA; без данных ячейки остаются пустыми
       p
-        a#auth-package-link
+        a#auth-docs-link
       p#auth-version
       p © #{new Date().getFullYear()} VIMP

package/src/client/views/includes/lobby.pug

@@ -21,7 +21,7 @@ div#lobby(style='display:none')
             input#profile-open(type='button', value='Profile')
             input#games-open-mine(type='button', value='My games')
             input#games-open-moderation(type='button', value='Moderation', style='display:none')
-            //- журнал клиентских ошибок (plan/client-reports, этап 5): только админ
+            //- журнал клиентских ошибок: только админ
             input#reports-open(type='button', value='Errors', style='display:none')
         hr.lobby-divider
         h3.lobby-section-title= 'HOST A GAME'
@@ -67,8 +67,8 @@ div#lobby(style='display:none')
               span#leaderboard-total
             ol#lobby-leaderboard-list
             p#lobby-my-placement
-    //- футер: ссылку и версию пакета движка проставляет LobbyView
-    //- (engineVersion.js + lib/packageLink.js)
+    //- футер: ссылка на документацию статична, версию пакета движка
+    //- проставляет LobbyView (engineVersion.js)
     div#lobby-footer
       p
         a#lobby-terms-link(target='_blank', rel='noopener') Terms of Service
@@ -76,6 +76,6 @@ div#lobby(style='display:none')
         |
         a#lobby-privacy-link(target='_blank', rel='noopener') Privacy Policy
       p
-        a#lobby-link
+        a#lobby-link(href='https://docs.vimp.lgick.dev', target='_blank', rel='noopener') docs
       p#lobby-version
       p © #{new Date().getFullYear()} VIMP

package/src/client/views/includes/reports.pug

@@ -1,4 +1,4 @@
-//- Журнал клиентских ошибок (plan/client-reports, этап 5): только админ.
+//- Журнал клиентских ошибок: только админ.
 //- Панель скрыта по умолчанию — открывается кнопкой «Errors» бейджа
 //- пользователя (#lobby-user в lobby.pug); id элементов перечислены в
 //- config/lobby.js. Подписи — по-английски, как и остальное лобби

package/src/config/authClient.js

@@ -2,8 +2,8 @@
 // config/lobby.js — auth-сервис живёт на отдельном домене/порте, поэтому
 // serviceUrl подставляется под конкретный деплой при сборке.
 export default {
-  // базовый URL центрального auth-сервиса (packages/auth). Дефолт — dev-порт
-  // из packages/auth/src/config/auth.js; в проде подставляется Vite'ом из
+  // базовый URL центрального auth-сервиса. Дефолт — dev-порт
+  // из конфига auth-сервиса; в проде подставляется Vite'ом из
   // VITE_AUTH_SERVICE_URL (см. Dockerfile — тот же VIMP_AUTH_SERVICE_URL,
   // что и серверный master/main.js). Этот модуль импортируется и серверным
   // master/main.js под чистым Node, где import.meta.env не определён —
@@ -14,7 +14,7 @@ export default {
     'http://localhost:3010',
 
   // issuer, которым central auth-сервис подписывает identity-токен; должен
-  // совпадать с packages/auth/src/config/auth.js: jwt.issuer — хост сверяет
+  // совпадать с jwt.issuer из конфига auth-сервиса — хост сверяет
   // claim iss токена с этим значением при проверке подписи по /jwks
   issuer: 'vimp-auth',
 

package/src/config/lobby.js

@@ -300,11 +300,11 @@ export default {
     joinRetryWindowMs: 45000,
   },
 
-  // приёмник выгрузок отладочного контура (этап 6 плана plan/done/ai-debug):
+  // приёмник выгрузок отладочного контура:
   // маршрут поднимается мастером только в dev, в проде вернёт 404
   debugReportUrl: '/debug/report',
 
-  // журнал клиентских ошибок (plan/client-reports): приём на том же боксе,
+  // журнал клиентских ошибок: приём на том же боксе,
   // что раздал страницу, — лобби-мастер или dedicated
   clientReportUrl: '/client-reports',
 
@@ -350,9 +350,8 @@ export default {
     myPlacementId: 'lobby-my-placement',
 
     // футер: версия npm-пакета движка, запечённая в бандл при сборке
-    // (client/lib/engineVersion.js), и ссылка на его страницу
+    // (client/lib/engineVersion.js)
     versionId: 'lobby-version',
-    linkId: 'lobby-link',
   },
 
   // реестр игр (master-game-registry, этап 4): заявка разработчика и панель
@@ -489,7 +488,7 @@ export default {
     },
   },
 
-  // журнал клиентских ошибок (plan/client-reports, этап 5): только админ.
+  // журнал клиентских ошибок: только админ.
   // URL и id элементов — здесь, как у панели реестра игр (reports.pug)
   clientReports: {
     urls: {

package/src/config/opcodes.js

@@ -1,6 +1,7 @@
 // Разметка бинарного snapshot-протокола (порт SHOT_DATA).
 // Единый источник для хоста (упаковка) и клиента (распаковка) — обе стороны
-// живут в Rust-ядре: packages/engine/core/src/snapshot.rs (pack) и packages/engine/core/src/client/unpack.rs.
+// живут в Rust-ядре: vimp-engine-core/src/snapshot.rs (pack) и
+// vimp-engine-core/src/client/unpack.rs.
 
 // версия контракта движок ↔ игра-плагин (GameManifest, HostPlugin,
 // ClientPlugin, Wasm Host ABI — docs/{en,ru}/plugin-api.md).

package/src/devtools/contract/loadContext.js

@@ -14,7 +14,7 @@ import { createGameConfigView } from '../../lib/gameConfigView.js';
 // модули; исходники читаются только там, где проверяется буква кода
 // (engineApi литералом или импортом).
 
-// каталог движка (packages/engine) — из него берётся версия крейта, с
+// каталог пакета движка — из него берётся версия крейта, с
 // которой сверяется пин игры. core/Cargo.toml числится в "files"
 // package.json именно ради этого: иначе в установке из npm версии крейта
 // нет, и правило A5 проверяло бы пин только внутри монорепозитория
@@ -170,7 +170,7 @@ async function readEngineCoreVersion() {
 // версия пакета в секции [package] — первый `version = "…"` до следующей
 // секции; TOML-парсера в зависимостях движка нет, а формат здесь наш.
 //
-// Копия живёт в packages/create-vimp-game/src/versions.js: скаффолдер
+// Копия живёт в create-vimp-game (src/versions.js): скаффолдер
 // ставится через `npm create` и обязан работать без движка в зависимостях.
 // Разбор обязан совпадать — правьте обе или ни одной (см. тест
 // tests/scaffold/versions.test.js).

package/src/devtools/contract/rules/a7-package-repository.js

@@ -1,17 +1,16 @@
 import { WARN, skip, verdict } from '../result.js';
 import { resolveProjectUrl } from '../../../lib/packageLink.js';
 
-// Игра без объявленного homepage/repository собирается и играется — это не
-// отказ. Но движок показывает ссылку на проект в футере формы входа, и берёт
-// он её только из этих полей (фолбэка нет, см. lib/packageLink.js): без них
-// ячейка футера у игроков останется пустой, а заметить это без подсказки негде.
+// Игра без объявленного repository собирается и играется — это не
+// отказ. Но реестр игр в лобби показывает ссылку на проект, и берёт он её
+// только из него (фолбэка нет, см. lib/packageLink.js): без них строка
+// игры останется без ссылки, а заметить это без подсказки негде.
 // Отсюда warn — под --strict он становится ошибкой.
 export default {
   id: 'A7',
   name: 'packageRepository',
   level: WARN,
-  title:
-    'package.json declares homepage or repository (the #auth footer links to it)',
+  title: 'package.json declares repository (the games registry links to it)',
 
   check(ctx) {
     if (!ctx.pkg) {
@@ -23,8 +22,8 @@ export default {
     }
 
     return verdict([
-      'neither "repository" nor "homepage" resolves to a project URL — ' +
-        "the game's entry form will show no project link",
+      '"repository" does not resolve to a project URL — ' +
+        "the game's registry entry will show no project link",
     ]);
   },
 };

package/src/devtools/contract/rules/index.js

@@ -38,7 +38,7 @@ import e6 from './e6-sound-spatial.js';
 import e7 from './e7-map-game-field.js';
 
 // Порядок групп — порядок отчёта: A пакет и сборка, B host, C client,
-// D снапшот, E ассеты (plan/create-vimp-game/stage_1.md).
+// D снапшот, E ассеты.
 export const rules = [
   a1,
   a2,

package/src/devtools/invariants.js

@@ -19,7 +19,7 @@ export const SKIP = 'skip';
 // не берётся судить покрытие схемы» (встроенный смоук на чужой игре)
 export const ALL_KEYS_UNAUDITED = '*';
 
-// список проверок в порядке plan/done/ai-debug/stage_3.md
+// список проверок
 const CHECKS = [
   [1, 'finiteValues', 'no NaN/Infinity in decoded fields and hot buffer'],
   [2, 'snapshotKeysUsed', 'every snapshot key produced at least one row'],

package/src/host/DebugRecorder.js

@@ -1,6 +1,6 @@
 import clock from '../lib/clock.js';
 
-// Рекордер живого матча (этап 6 плана plan/done/ai-debug): пишет то, что headless
+// Рекордер живого матча: пишет то, что headless
 // не воспроизводит — реальный WebRTC, PixiJS и живой ввод человека — ровно в
 // формат сценария headless-runner'а (devtools/ScenarioRunner.js). Баг,
 // пойманный человеком в браузере, догоняется потом `npm run sim:replay`

package/src/host/HostGame.js

@@ -16,6 +16,7 @@ import closeCodes from '../config/closeCodes.js';
 import clock from '../lib/clock.js';
 import { createResumeKey } from '../lib/resumeKey.js';
 import GameCoreAdapter from './GameCoreAdapter.js';
+import { commandFailureReport } from './commandFailure.js';
 import DebugRecorder from './DebugRecorder.js';
 import enginePkg from '../../package.json' with { type: 'json' };
 
@@ -252,7 +253,7 @@ export default class HostGame {
     this._networkSendRate = data.timers.networkSendRate;
     this._snapshotManager = new SnapshotThrottle(this._networkSendRate);
 
-    // рекордер живого матча (этап 6 плана plan/done/ai-debug) — только в dev-режиме;
+    // рекордер живого матча — только в dev-режиме;
     // в проде null, и все точки записи ниже вырождаются в ?.
     this._recorder = this._isDevMode ? new DebugRecorder() : null;
 
@@ -317,19 +318,22 @@ export default class HostGame {
       currentMap: data.currentMap,
     });
 
-    this._commandProcessor = new CommandProcessor({
-      participants: this._participants,
-      chat: this._chat,
-      scripted: this._scripted,
-      roundManager: this._roundManager,
-      voteCoordinator: this._voteCoordinator,
-      timerManager: this._timerManager,
-      playerDataSync: this._playerDataSync,
-      teams: this._teams,
-      spectatorTeam: this._spectatorTeam,
-      spectatorId: this._spectatorId,
-      isDevMode: this._isDevMode,
-    });
+    this._commandProcessor = new CommandProcessor(
+      {
+        participants: this._participants,
+        chat: this._chat,
+        scripted: this._scripted,
+        roundManager: this._roundManager,
+        voteCoordinator: this._voteCoordinator,
+        timerManager: this._timerManager,
+        playerDataSync: this._playerDataSync,
+        teams: this._teams,
+        spectatorTeam: this._spectatorTeam,
+        spectatorId: this._spectatorId,
+        isDevMode: this._isDevMode,
+      },
+      { onError: (command, error) => this._reportCommandError(command, error) },
+    );
 
     // игровые чат-команды и коды системных сообщений из HostPlugin
     for (const command of hostPlugin.chatCommands) {
@@ -349,6 +353,7 @@ export default class HostGame {
     this._checkpointSink = null; // ({ meta, core, final }) => void
     // здоровье хоста (host-migration этап 9a): раз в окно цикла
     this._healthSink = null; // (health) => void
+    this._diagnosticSink = null; // ({ kind, message, stack }) => void
     this._checkpointIntervalMs = 0; // 0 — периодических точек нет
     this._lastCheckpointAt = 0;
     this._checkpointRequest = null; // { final } — точка на ближайшем кадре
@@ -738,7 +743,7 @@ export default class HostGame {
     this._mapList.push(...Object.keys(this._maps));
   }
 
-  // ***** отладочный контур (этап 6 плана plan/done/ai-debug) ***** //
+  // ***** отладочный контур ***** //
   // Всё ниже живёт под флагом isDevMode: в проде рекордера нет, а дамп
   // отдаёт только то, что и так знает мета.
 
@@ -1042,6 +1047,21 @@ export default class HostGame {
 
   // ***** здоровье хоста (host-migration этап 9a) ***** //
 
+  /**
+   * Приёмник сбоев кода игры, пойманных хостом: { kind, message, stack }.
+   * @param {Function|null} sink
+   */
+  setDiagnosticSink(sink) {
+    this._diagnosticSink = typeof sink === 'function' ? sink : null;
+  }
+
+  // сбой чат-команды игры: отчёт собирает commandFailure.js (одна строка
+  // сообщения, стек без текста ошибки); бросок приёмника гасит
+  // CommandProcessor._fail
+  _reportCommandError(command, error) {
+    this._diagnosticSink?.(commandFailureReport(command, error));
+  }
+
   /**
    * Приёмник метрик здоровья: раз в окно игрового цикла (~1 с) —
    * { tickRate, maxGapMs, lostMs, windowMs, peerRttMedian, peerCount }.