vimp-engine 0.38.0 → 0.38.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lgick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,9 +1,15 @@
 # vimp-engine
 
-VIMP — движок-приложение: мастер (лобби, WebRTC-сигналинг), P2P-транспорт,
-Worker-хост, мета-модули матча, MVC-каркас клиента. Игровые правила
-(например, `@vimp-games/tanks`) подключаются динамически через
-[plugin-api](https://github.com/lgick/vimp/blob/main/docs/en/plugin-api.md)
-— этот пакет их не содержит.
+The VIMP engine SDK for game plugins: the browser host and client runtime,
+the standalone mode (`vimp-engine/standalone`) and the CLI tools `vimp-sim`
+and `vimp-contract`. Game rules live in separate plugin packages that the
+engine loads at runtime through the
+[plugin contract](https://docs.vimp.lgick.dev/en/plugin-api).
 
-Документация: https://github.com/lgick/vimp/tree/main/docs/en
+Start a game:
+
+```bash
+npm create vimp-game my-game
+```
+
+Documentation: https://docs.vimp.lgick.dev

package/bin/vimp-sim.js

@@ -40,8 +40,8 @@ const BUILTIN_NOTICE =
   'notice: the built-in smoke scenario is running against --game. It only\n' +
   'notice: proves the loop closes on this plugin: key coverage (invariant 2)\n' +
   'notice: and prediction drift (invariant 9) are skipped — both need a\n' +
-  'notice: scenario written for your game. See § Scenario format in the\n' +
-  "notice: engine's docs/en/debugging.md (github.com/lgick/vimp), then run\n" +
+  'notice: scenario written for your game. See § Scenario format at\n' +
+  'notice: https://docs.vimp.lgick.dev/en/debugging#scenario-format, then run\n' +
   'notice: vimp-sim --scenario <file>.\n\n';
 
 // типичная опечатка «--core без --game»: фикстурное ядро — обычный JS и

package/core/Cargo.toml

@@ -1,10 +1,11 @@
 [package]
 name = "vimp-engine-core"
-version = "0.23.2"
+version = "0.23.3"
 edition = "2024"
-description = "VIMP — движковый каркас симуляции (физика, карта, снапшот-фрейминг, интерполяция/предикт/raycast-примитивы, нав-утилиты). Без wasm-bindgen — обёртки для WASM-ABI собирает game-crate."
+description = "VIMP engine simulation core: physics, map, snapshot framing, interpolation/prediction/raycast primitives, navigation utilities. No wasm-bindgen — the game crate builds the WASM ABI wrappers."
 license = "MIT"
-repository = "https://github.com/lgick/vimp"
+homepage = "https://docs.vimp.lgick.dev/en/core"
+documentation = "https://docs.rs/vimp-engine-core"
 readme = "README.md"
 
 [lib]

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "vimp-engine",
-  "version": "0.38.0",
-  "description": "VIMP — движок-приложение (мастер, P2P-транспорт, Worker-хост, мета, MVC-каркас клиента)",
+  "version": "0.38.2",
+  "description": "VIMP engine SDK: browser host and client runtime, standalone mode and CLI tools (vimp-sim, vimp-contract) for VIMP game plugins",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/lgick/vimp.git"
+    "url": "git+ssh://git@github.com/lgick/vimp.git",
+    "directory": "packages/engine"
   },
-  "homepage": "https://github.com/lgick/vimp#readme",
+  "homepage": "https://docs.vimp.lgick.dev",
   "type": "module",
   "engines": {
     "node": ">=20.11.0"
@@ -23,7 +24,12 @@
   },
   "files": [
     "src/lib",
+    "!src/lib/clientIp.js",
+    "!src/lib/rateLimiter.js",
+    "!src/lib/security.js",
     "src/config",
+    "!src/config/env.js",
+    "!src/config/master.js",
     "src/host",
     "src/client",
     "!src/client/_*",
@@ -31,7 +37,8 @@
     "src/devtools",
     "tests/fixtures",
     "core/Cargo.toml",
-    "bin"
+    "bin",
+    "!bin/vimp-surface.js"
   ],
   "scripts": {
     "predev": "node scripts/sync-pixi-vendor.mjs",

package/src/client/components/controller/ClientReports.js

@@ -25,7 +25,8 @@ export default class ClientReportsCtrl {
   }
 
   // роль решает только видимость кнопки «Errors»: доступ к данным проверяет
-  // мастер, а auth перечитывает роль из БД
+  // мастер, а права админа auth-сервис проверяет сам, по нику из
+  // VIMP_ADMIN_NICKS
   setAdmin(isAdmin) {
     this._view.setAdmin(isAdmin);
   }

package/src/client/components/controller/Games.js

@@ -42,7 +42,7 @@ export default class GamesCtrl {
   }
 
   // роль решает только видимость кнопки модерации: доступ к данным
-  // проверяет мастер, а запись — auth-сервис по роли из БД
+  // проверяет мастер, а запись — auth-сервис, по нику из VIMP_ADMIN_NICKS
   setAdmin(isAdmin) {
     this._view.setAdmin(isAdmin);
 

package/src/client/components/controller/LobbyAuth.js

@@ -101,8 +101,11 @@ export default class LobbyAuthCtrl {
     return this.register(this._view.getNickValue());
   }
 
+  // флаг закрывает только построение URL (хэш verifier считается
+  // асинхронно): два построения подряд — лишняя работа. После navigate() он
+  // снят — отменённый переход или возврат кнопкой «Назад» не должен
+  // оставить экран без регистрации и входа
   async restore(provider) {
-    // двойной клик перезаписал бы verifier попытки, уже ушедшей на auth
     if (this._busy) {
       return;
     }
@@ -112,8 +115,9 @@ export default class LobbyAuthCtrl {
     try {
       this._navigate(await this._model.restoreUrl(provider));
     } catch {
-      this._busy = false;
       this._view.renderRestoreError('failed');
+    } finally {
+      this._busy = false;
     }
   }
 

package/src/client/components/controller/Profile.js

@@ -32,6 +32,7 @@ export default class ProfileCtrl {
     this._model = model;
     this._view = view;
     this._navigate = navigate;
+    this._linking = false;
 
     this.publisher = new Publisher();
 
@@ -52,13 +53,22 @@ export default class ProfileCtrl {
     this._view.show();
   }
 
-  // кнопки вида неактивны без согласий; проверка здесь — второй рубеж
+  // кнопки вида неактивны без согласий; проверка здесь — второй рубеж.
+  // Флаг закрывает только построение URL — как у LobbyAuthCtrl.restore()
   async link(provider) {
-    if (!this._view.consentGiven()) {
+    if (this._linking || !this._view.consentGiven()) {
       return;
     }
 
-    this._navigate(await this._model.linkUrl(provider));
+    this._linking = true;
+
+    try {
+      this._navigate(await this._model.linkUrl(provider));
+    } catch {
+      this._view.renderError({ area: 'link', code: 'failed' });
+    } finally {
+      this._linking = false;
+    }
   }
 
   unlink(provider) {

package/src/client/components/model/LobbyAuth.js

@@ -1,6 +1,7 @@
 import Publisher from '../../../lib/Publisher.js';
 import { decodeJwtPayload } from '../../../lib/jwt.js';
 import { isValidNick } from '../../../lib/validators.js';
+import { isSessionRejected } from '../../lib/authApi.js';
 
 // Singleton LobbyAuthModel
 
@@ -25,6 +26,7 @@ export default class LobbyAuthModel {
    * @param {Storage} [deps.sessionStore] - попытка OAuth, уведомление.
    * @param {boolean} [deps.isDev] - принимать ?devSession= (dev-сборка).
    * @param {Function} [deps.getLocation]
+   * @param {Function} [deps.now] - () → мс эпохи по часам устройства.
    */
   constructor(
     config,
@@ -35,6 +37,7 @@ export default class LobbyAuthModel {
       sessionStore = sessionStorage,
       isDev = false,
       getLocation = () => window.location,
+      now = () => Date.now(),
     } = {},
   ) {
     if (lobbyAuthModel) {
@@ -50,9 +53,11 @@ export default class LobbyAuthModel {
     this._sessionStore = sessionStore;
     this._isDev = isDev;
     this._getLocation = getLocation;
+    this._now = now;
 
     this._session = null;
     this._token = null;
+    this._tokenExpiresAt = null;
     this._profile = null;
     this._clientConfig = null;
     this._urlParams = { code: null, error: null, devSession: null };
@@ -100,7 +105,15 @@ export default class LobbyAuthModel {
 
     this.publisher.emit('loading');
 
-    const cfg = await this._api.clientConfig();
+    // секрет читается до сети: настройки и токен уходят одновременно, лобби
+    // вернувшегося игрока открывается на круг запроса раньше
+    const stored = this._storage.getItem(sessionStorageKey);
+    // значение не того формата секретом не является: на auth не уходит
+    const session = stored && SESSION_RE.test(stored) ? stored : null;
+    const [cfg, res] = await Promise.all([
+      this._api.clientConfig(),
+      session ? this._api.token(session) : null,
+    ]);
 
     if (!cfg.ok) {
       this.publisher.emit('service-error');
@@ -115,8 +128,6 @@ export default class LobbyAuthModel {
 
     this._urlParams = { code: null, error: null, devSession: null };
 
-    const session = this._storage.getItem(sessionStorageKey);
-
     if (!session) {
       await this._bootWithoutSession(attempt, code, error);
       return;
@@ -124,13 +135,14 @@ export default class LobbyAuthModel {
 
     this._session = session;
 
-    const res = await this._api.token(session);
-
     if (res.ok) {
       this._adopt({ token: res.data.token, profile: res.data.profile });
+      // уведомление писала вкладка, потерявшая сессию в комнате; под принятой
+      // личностью оно ни к чему и не должно всплыть на Welcome позже
+      this._takeNotice();
       await this._finishLink(attempt, code, error);
       this._emitAuthenticated();
-    } else if (res.status === 401) {
+    } else if (isSessionRejected(res)) {
       this._forgetSession();
       this.publisher.emit('welcome', { notice: 'profileGone' });
     } else {
@@ -244,7 +256,7 @@ export default class LobbyAuthModel {
       this._storage.setItem(this._config.sessionStorageKey, session);
     }
 
-    this._token = token;
+    this._setToken(token);
     this._profile = profile;
   }
 
@@ -257,9 +269,18 @@ export default class LobbyAuthModel {
   }
 
   _forgetSession() {
-    this._storage.removeItem(this._config.sessionStorageKey);
+    const key = this._config.sessionStorageKey;
+
+    // в хранилище может лежать секрет ДРУГОГО профиля: его записала вкладка,
+    // сменившая личность браузера, пока эта доигрывала матч под прежней.
+    // Стирается только свой — у профиля без привязки он единственный ключ
+    if (this._storage.getItem(key) === this._session) {
+      this._storage.removeItem(key);
+    }
+
     this._session = null;
     this._token = null;
+    this._tokenExpiresAt = null;
     this._profile = null;
   }
 
@@ -335,7 +356,7 @@ export default class LobbyAuthModel {
     const res = await this._api.token(this._session);
 
     if (res.ok) {
-      this._token = res.data.token;
+      this._setToken(res.data.token);
       this._profile = res.data.profile;
       this.publisher.emit('token-renewed', {
         expiresAt: this.getTokenExpiresAt(),
@@ -343,7 +364,7 @@ export default class LobbyAuthModel {
       return 'ok';
     }
 
-    if (res.status === 401) {
+    if (isSessionRejected(res)) {
       this._forgetSession();
       this.publisher.emit('session-lost');
       return 'lost';
@@ -385,19 +406,36 @@ export default class LobbyAuthModel {
   }
 
   // роль из payload токена — ПОДСКАЗКА ИНТЕРФЕЙСУ (показывать ли кнопку
-  // модерации), не право: доступ к данным проверяет мастер по подписи, а
-  // запись — auth-сервис, перечитывая роль из БД
+  // модерации), не право: права админа auth-сервис проверяет сам, по нику
+  // из VIMP_ADMIN_NICKS
   getRole() {
     return decodeJwtPayload(this._token)?.role ?? 'user';
   }
 
-  // срок входа (мс эпохи) или null — неизвестен. Вкладка с кончающимся
-  // токеном не принимает роль хоста: register_host/reclaim_host предъявят
-  // его мастеру посреди матча
-  getTokenExpiresAt() {
-    const exp = decodeJwtPayload(this._token)?.exp;
+  // Срок токена в шкале часов УСТРОЙСТВА: момент получения плюс время жизни
+  // из самого токена (exp − iat — оба выставлены часами auth-сервиса).
+  // Сдвиг часов устройства на срок не влияет. Токен без iat — срок по exp
+  _setToken(token) {
+    const payload = decodeJwtPayload(token);
+    const exp = payload?.exp;
+    const iat = payload?.iat;
 
-    return typeof exp === 'number' ? exp * 1000 : null;
+    this._token = token;
+
+    if (typeof exp !== 'number') {
+      this._tokenExpiresAt = null;
+    } else if (typeof iat === 'number' && exp > iat) {
+      this._tokenExpiresAt = this._now() + (exp - iat) * 1000;
+    } else {
+      this._tokenExpiresAt = exp * 1000;
+    }
+  }
+
+  // срок входа (мс эпохи по часам устройства) или null — неизвестен.
+  // Вкладка с кончающимся токеном не принимает роль хоста:
+  // register_host/reclaim_host предъявят его мастеру посреди матча
+  getTokenExpiresAt() {
+    return this._tokenExpiresAt;
   }
 
   getProfile() {

package/src/client/components/model/Profile.js

@@ -1,4 +1,5 @@
 import Publisher from '../../../lib/Publisher.js';
+import { isSessionRejected } from '../../lib/authApi.js';
 
 // Singleton ProfileModel
 
@@ -107,9 +108,10 @@ export default class ProfileModel {
   }
 
   // один запрос за раз; успех — data тела ответа (null у 204); отказ —
-  // undefined и событие error, а при 401 (сессия мертва: профиль удалён в
-  // другой вкладке, срок вышел) — вместо error событие left с уведомлением
-  // profileGone, уже после снятия busy; запрос во время другого не стартует
+  // undefined и событие error. Если auth-сервис не нашёл сессию
+  // (401 sessionUnknown: профиль удалён или сессия закрыта в другой вкладке) —
+  // вместо error событие left с уведомлением profileGone, уже после снятия
+  // busy; запрос во время другого не стартует
   async _run(area, request) {
     if (this._busy) {
       return undefined;
@@ -131,7 +133,7 @@ export default class ProfileModel {
       return res.data;
     }
 
-    if (res.status === 401) {
+    if (isSessionRejected(res)) {
       this._leave('profileGone');
     } else {
       this.publisher.emit('error', { area, code: res.error });

package/src/client/components/view/Auth.js

@@ -13,7 +13,8 @@ export default class AuthView {
   // texts — игровые тексты формы (authSchema.texts: title, sections);
   // сам каркас (auth.pug) нейтрален и текстов игры не содержит.
   // params — та же дескрипторная схема формы, что и у room-формы
-  // (docs/en/plugin-api.md "Form schema"), едет по сети в PS_AUTH_DATA
+  // (docs.vimp.lgick.dev/en/plugin-api "Form schema"), едет по сети в
+  // PS_AUTH_DATA
   constructor(model, elems, texts = null, params = null) {
     if (authView) {
       return authView;
@@ -63,7 +64,8 @@ export default class AuthView {
   }
 
   // строит контролы формы игрока из той же дескрипторной схемы, что и
-  // room-форма (единый formBuilder, docs/en/plugin-api.md "Form schema")
+  // room-форма (единый formBuilder, docs.vimp.lgick.dev/en/plugin-api "Form
+  // schema")
   _renderFields(elems, params) {
     if (!Array.isArray(params)) {
       return;

package/src/client/components/view/LobbyAuth.js

@@ -1,4 +1,5 @@
 import Publisher from '../../../lib/Publisher.js';
+import { ENGINE_VERSION } from '../../lib/engineVersion.js';
 
 // Singleton LobbyAuthView
 
@@ -6,7 +7,7 @@ let lobbyAuthView;
 
 const REGISTER_ERRORS = {
   invalidNick:
-    'Invalid nick: 2–14 characters, starting with a letter. Letters, digits, spaces, "_" and "#" are allowed; the last character is a letter, digit or "_".',
+    'Invalid nick: 2–15 characters, starting with a letter. Letters, digits, spaces, "_" and "#" are allowed; the last character is a letter, digit or "_".',
   nickTaken: 'This nick is already taken.',
   turnstileBlocked:
     'Security check blocked. Please disable your ad blocker (or Brave Shields) and click Retry.',
@@ -14,7 +15,7 @@ const REGISTER_ERRORS = {
   turnstileFailed: 'Security check failed. Please try again.',
   turnstileUnavailable:
     'Registration is temporarily unavailable. Please try again later.',
-  rateLimited: 'Too many attempts. Please wait a minute and try again.',
+  rateLimited: 'Too many attempts. Please try again later.',
   termsRequired: 'The terms have been updated. Reload the page and try again.',
 };
 
@@ -56,6 +57,7 @@ export default class LobbyAuthView {
     this._statusText = byId(elems.statusTextId);
     this._statusRetry = byId(elems.statusRetryId);
     this._welcome = byId(elems.welcomeId);
+    this._footer = byId(elems.footerId);
     this._notice = byId(elems.noticeId);
     this._nickInput = byId(elems.nickInputId);
     this._nickError = byId(elems.nickErrorId);
@@ -64,7 +66,7 @@ export default class LobbyAuthView {
     this._register = byId(elems.registerId);
     this._terms = byId(elems.termsId);
     this._privacy = byId(elems.privacyId);
-    this._lifetime = byId(elems.lifetimeId);
+    byId(elems.versionId).textContent = ENGINE_VERSION;
     this._restore = byId(elems.restoreId);
     this._providers = byId(elems.providersId);
     this._restoreError = byId(elems.restoreErrorId);
@@ -114,6 +116,7 @@ export default class LobbyAuthView {
     this._enterAuth();
     this._status.style.display = 'block';
     this._welcome.style.display = 'none';
+    this._footer.style.display = 'none';
     this._statusText.textContent = text;
     this._statusRetry.style.display = retry ? '' : 'none';
   }
@@ -125,14 +128,11 @@ export default class LobbyAuthView {
     this._enterAuth();
     this._status.style.display = 'none';
     this._welcome.style.display = 'block';
+    this._footer.style.display = '';
 
     this._notice.textContent = NOTICES[notice] ?? '';
     this._terms.href = clientConfig.legal.termsUrl;
     this._privacy.href = clientConfig.legal.privacyUrl;
-    this._lifetime.textContent =
-      'Your profile is kept in this browser and is deleted after ' +
-      `${clientConfig.accounts.inactiveDays} days of inactivity. ` +
-      'Link an account later to keep it longer.';
 
     this._providerButtons.forEach(btn => {
       btn.style.display = providers.includes(btn.dataset.provider)

package/src/client/components/view/Profile.js

@@ -65,7 +65,6 @@ export default class ProfileView {
     this._close = byId(elems.closeBtnId);
     this._nick = byId(elems.nickId);
     this._status = byId(elems.statusId);
-    this._linkCard = byId(elems.linkCardId);
     this._benefits = byId(elems.benefitsId);
     this._providers = byId(elems.providersId);
     this._consent = byId(elems.consentId);

package/src/client/lib/authApi.js

@@ -7,6 +7,15 @@
 
 const JSON_HEADERS = { 'Content-Type': 'application/json' };
 
+// Единственный код, которым auth-сервис сообщает, что сессии нет.
+// invalidSession («секрет не того формата») вердиктом не считается: клиент
+// шлёт только секрет верного формата, и такой ответ значит, что заголовок
+// Authorization не дошёл до сервиса (редирект, прокси, сбой сервиса). Как и
+// 401 без кода, это сбой: секрет по нему не стирается — у профиля без
+// привязки он единственный ключ
+export const isSessionRejected = res =>
+  res.status === 401 && res.error === 'sessionUnknown';
+
 /**
  * @param {Object} options
  * @param {string} options.serviceUrl - базовый URL auth-сервиса.

package/src/client/lib/formBuilder.js

@@ -4,9 +4,9 @@ import { resolveDescriptor } from '../../lib/formControls.js';
 import { toDisplay, toStored, isNumericField } from '../../lib/formUnit.js';
 
 // Общий билдер полей форм (room-форма и auth-форма используют один
-// контракт дескрипторов — docs/en/plugin-api.md, раздел "Form schema").
-// control: 'select'|'text'|'checkbox'|'radio'; все контролы — нативные
-// элементы формы, без визуальной кастомизации.
+// контракт дескрипторов — docs.vimp.lgick.dev/en/plugin-api, раздел "Form
+// schema"). control: 'select'|'text'|'checkbox'|'radio'; все контролы —
+// нативные элементы формы, без визуальной кастомизации.
 //
 // Имя контрола приезжает от игры и разрешается через append-only реестр
 // (lib/formControls.js): имена, выведенные из эксплуатации в v3 ('range',
@@ -270,7 +270,8 @@ const builders = {
 // control» на имени, которое реестр считает живым
 export const FORM_CONTROLS = Object.keys(builders);
 
-// строит одно поле формы по дескриптору (docs/en/plugin-api.md, "Form schema")
+// строит одно поле формы по дескриптору (docs.vimp.lgick.dev/en/plugin-api,
+// "Form schema")
 export function buildField(descriptor, ctx = {}) {
   // алиас выведенного контрола ('range' → numeric 'text') разрешается
   // здесь же, где строится поле, и теми же правилами, что в валидации
@@ -291,10 +292,10 @@ export function buildField(descriptor, ctx = {}) {
 }
 
 // засеивает default каждого дескриптора room-формы значением из roomDefaults
-// (docs/en/plugin-api.md "Form schema": roomDefaults остаётся единственным
-// источником значений по умолчанию); явный descriptor.default, если он есть
-// в схеме, побеждает. Вынесено из populateRoomForm (main.js), чтобы этот же
-// код был накрыт тестом, а не продублирован в нём
+// (docs.vimp.lgick.dev/en/plugin-api "Form schema": roomDefaults остаётся
+// единственным источником значений по умолчанию); явный descriptor.default,
+// если он есть в схеме, побеждает. Вынесено из populateRoomForm (main.js),
+// чтобы этот же код был накрыт тестом, а не продублирован в нём
 export function mergeRoomDefaults(descriptors, roomDefaults) {
   return descriptors.map(descriptor => ({
     default: roomDefaults[descriptor.name],

package/src/client/lib/hostCaps.js

@@ -70,8 +70,9 @@ export function buildHostCaps(
 
 /**
  * Хватит ли срока токена, чтобы вкладка могла принять роль хоста: хост
- * предъявляет токен мастеру посреди матча (register_host, reclaim_host), а
- * продления нет.
+ * предъявляет токен мастеру посреди матча (register_host, reclaim_host).
+ * Токен обычно продлевается заранее; проверка — страховка на случай, когда
+ * продление не удаётся.
  * @param {number|null} expiresAt - мс эпохи; null — неизвестно (не мешает).
  * @param {number} minLifetimeMs
  * @param {number} [now]

package/src/client/lib/sessionSync.js

@@ -0,0 +1,45 @@
+/**
+ * Что делать вкладке лобби, когда в localStorage лежит не тот секрет
+ * сессии, с которым она работает: личность вкладки меняется только
+ * перезагрузкой.
+ * @param {Object} ctx
+ * @param {string|null} ctx.storedSession - секрет в хранилище.
+ * @param {string|null} ctx.currentSession - секрет, с которым работает вкладка.
+ * @param {boolean} ctx.inRoom - вкладка в комнате.
+ * @returns {'reload'|'ignore'}
+ */
+export function decideStoredSession({ storedSession, currentSession, inRoom }) {
+  if (storedSession === currentSession) {
+    return 'ignore';
+  }
+
+  // матч доигрывается под прежней личностью; новую покажет следующая загрузка
+  return inRoom ? 'ignore' : 'reload';
+}
+
+/**
+ * То же решение по событию storage: секрет изменил другой контекст.
+ * @param {Object} ctx
+ * @param {{key: string|null, newValue: string|null}} ctx.event - событие storage.
+ * @param {string} ctx.sessionKey - ключ секрета сессии.
+ * @param {string|null} ctx.currentSession - секрет, с которым работает вкладка.
+ * @param {boolean} ctx.inRoom - вкладка в комнате.
+ * @returns {'reload'|'ignore'}
+ */
+export function decideSessionStorageChange({
+  event,
+  sessionKey,
+  currentSession,
+  inRoom,
+}) {
+  // key === null — хранилище очищено целиком
+  if (event.key !== null && event.key !== sessionKey) {
+    return 'ignore';
+  }
+
+  return decideStoredSession({
+    storedSession: event.key === null ? null : event.newValue,
+    currentSession,
+    inRoom,
+  });
+}