vimp-engine 0.22.1 → 0.24.0

package/bin/vimp-surface.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  collectSurface,
+  formatSurface,
+  diffSurface,
+} from '../src/devtools/surface/collect.js';
+
+// CLI слепка плагинной поверхности (этап 1 плана plugin-forward-compat):
+// без флага печатает расхождение с закоммиченным contract/surface.json и
+// возвращает 1 при нарушении И1/И3, с --write перезаписывает слепок.
+// Внутренний инструмент репозитория движка: в поле `bin` публикуемого
+// пакета он не значится.
+
+const SURFACE_PATH = fileURLToPath(
+  new URL('../contract/surface.json', import.meta.url),
+);
+
+const USAGE = `Usage: vimp-surface [options]
+
+  --write   rewrite contract/surface.json with the collected surface
+  --help
+`;
+
+async function main(argv) {
+  if (argv.includes('--help')) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const surface = await collectSurface();
+
+  if (argv.includes('--write')) {
+    await mkdir(path.dirname(SURFACE_PATH), { recursive: true });
+    await writeFile(SURFACE_PATH, formatSurface(surface));
+    process.stdout.write(`surface: written ${SURFACE_PATH}\n`);
+
+    return 0;
+  }
+
+  let committed;
+
+  try {
+    committed = JSON.parse(await readFile(SURFACE_PATH, 'utf8'));
+  } catch {
+    process.stderr.write(
+      `surface: no snapshot at ${SURFACE_PATH} — run ` +
+        '`npm run surface:update` to create it\n',
+    );
+
+    return 1;
+  }
+
+  const { violations, additions } = diffSurface(committed, surface);
+
+  for (const addition of additions) {
+    process.stdout.write(`surface: добавлено ${addition}\n`);
+  }
+
+  if (additions.length > 0 && violations.length === 0) {
+    process.stdout.write(
+      'слепок устарел, запусти `npm run surface:update` (добавление ' +
+        'поверхности совместимость не ломает)\n',
+    );
+  }
+
+  for (const violation of violations) {
+    process.stderr.write(`${violation}\n\n`);
+  }
+
+  if (violations.length === 0 && additions.length === 0) {
+    process.stdout.write('surface: слепок совпадает\n');
+  }
+
+  return violations.length > 0 ? 1 : 0;
+}
+
+main(process.argv.slice(2)).then(
+  code => {
+    process.exitCode = code;
+  },
+  err => {
+    process.stderr.write(`${err.message}\n`);
+    process.exitCode = 1;
+  },
+);

package/core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vimp-engine-core"
-version = "0.8.4"
+version = "0.9.1"
 edition = "2024"
 description = "VIMP — движковый каркас симуляции (физика, карта, снапшот-фрейминг, интерполяция/предикт/raycast-примитивы, нав-утилиты). Без wasm-bindgen — обёртки для WASM-ABI собирает game-crate."
 license = "MIT"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vimp-engine",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "description": "VIMP — движок-приложение (мастер, P2P-транспорт, Worker-хост, мета, MVC-каркас клиента)",
   "license": "MIT",
   "repository": {

package/src/client/lib/formBuilder.js

@@ -1,12 +1,23 @@
 import { anchorPattern } from '../../lib/formPattern.js';
 import { normalizeOptions } from '../../lib/formOptions.js';
+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'; все контролы — нативные
-// элементы формы, без визуальной кастомизации. Валидация — не нативная
-// (никаких браузерных попапов): collectFormErrors/renderFormErrors ниже
-// собирают и рисуют ошибки в разметку (#lobby-error/#auth-error).
+// элементы формы, без визуальной кастомизации.
+//
+// Имя контрола приезжает от игры и разрешается через append-only реестр
+// (lib/formControls.js): имена, выведенные из эксплуатации в v3 ('range',
+// 'number', 'toggle', 'segmented'), продолжают строиться алиасами своих
+// нативных замен (И1). Тот же резолв обязана делать авторитетная валидация
+// хоста (lib/validators.js) — иначе поле строится одним контролом, а
+// проверяется как другой.
+//
+// Валидация — не нативная (никаких браузерных попапов):
+// collectFormErrors/renderFormErrors ниже собирают и рисуют ошибки в
+// разметку (#lobby-error/#auth-error).
 // Проверяются только поля, у которых есть строка в DOM: ошибка на скрытом
 // поле игроку не видна и исправить её нечем — она просто запирает форму.
 
@@ -14,12 +25,6 @@ import { normalizeOptions } from '../../lib/formOptions.js';
 // resolveForcedValue не расходился с builders при добавлении нового
 const OPTION_CONTROLS = ['select', 'radio'];
 
-// числовое text-поле: unit задан или numeric:true. Правило одно на билдер и
-// на валидацию, поэтому живёт в одном месте
-function isNumeric(descriptor) {
-  return descriptor.numeric === true || descriptor.unit !== undefined;
-}
-
 // 'source' — спец-источник вариантов из каталога движка (например карты),
 // прокидывается вызывающей стороной через ctx.sources
 function resolveOptions(descriptor, ctx) {
@@ -43,11 +48,14 @@ function forcedValue(options) {
 // то же правило вне формы: solo-путь (boot.autoAuth) отвечает хосту без
 // всякой формы и должен прийти ровно к тому же значению, что и она
 export function resolveForcedValue(descriptor, ctx = {}) {
-  if (!OPTION_CONTROLS.includes(descriptor.control)) {
+  // после разрешения алиаса: 'segmented' — та же группа вариантов, что radio
+  const resolved = resolveDescriptor(descriptor);
+
+  if (!OPTION_CONTROLS.includes(resolved.control)) {
     return undefined;
   }
 
-  const forced = forcedValue(resolveOptions(descriptor, ctx));
+  const forced = forcedValue(resolveOptions(resolved, ctx));
 
   // форма отдала бы строку: и <option>.value, и <input type=radio>.value —
   // DOM-свойства, они всегда строки. Нестроковое значение (options: [1, 2])
@@ -56,15 +64,6 @@ export function resolveForcedValue(descriptor, ctx = {}) {
   return forced === undefined ? undefined : String(forced);
 }
 
-// unit:'s' — значение хранится в мс, показывается/редактируется в секундах
-function toDisplay(descriptor, value) {
-  return descriptor.unit === 's' ? value / 1000 : value;
-}
-
-function toStored(descriptor, value) {
-  return descriptor.unit === 's' ? value * 1000 : value;
-}
-
 function buildSelect(descriptor, ctx) {
   const el = document.createElement('select');
   const options = resolveOptions(descriptor, ctx);
@@ -109,7 +108,7 @@ function buildSelect(descriptor, ctx) {
 // вместо превращения его в 0 на сабмите
 function buildText(descriptor) {
   const el = document.createElement('input');
-  const numeric = isNumeric(descriptor);
+  const numeric = isNumericField(descriptor);
 
   el.type = 'text';
   // выпадашка прошлых значений/автозаполнения кроет форму, а подставить в
@@ -265,18 +264,27 @@ const builders = {
   radio: buildRadio,
 };
 
+// имена control, которые билдер умеет строить. Активный набор имён диктует
+// реестр (lib/formControls.js), и совпадение этих двух списков проверяет
+// tests/client/formControls.test.js: разъехавшись, они дали бы «unknown
+// control» на имени, которое реестр считает живым
+export const FORM_CONTROLS = Object.keys(builders);
+
 // строит одно поле формы по дескриптору (docs/en/plugin-api.md, "Form schema")
 export function buildField(descriptor, ctx = {}) {
-  const build = builders[descriptor.control];
+  // алиас выведенного контрола ('range' → numeric 'text') разрешается
+  // здесь же, где строится поле, и теми же правилами, что в валидации
+  const patched = resolveDescriptor(descriptor);
+  const build = builders[patched.control];
 
   if (!build) {
     throw new Error(`formBuilder: unknown control "${descriptor.control}"`);
   }
 
-  const field = build(descriptor, ctx);
+  const field = build(patched, ctx);
 
-  if (descriptor.default !== undefined) {
-    field.setValue(descriptor.default);
+  if (patched.default !== undefined) {
+    field.setValue(patched.default);
   }
 
   return field;
@@ -370,7 +378,7 @@ function validateField(descriptor, field) {
   const isEmpty = isText
     ? raw === ''
     : value === undefined || value === null || value === '';
-  const numeric = isText && isNumeric(descriptor);
+  const numeric = isText && isNumericField(descriptor);
 
   // числовое поле всегда несёт число и «необязательным» быть не может:
   // пустой ввод getValue() подменяет default'ом (чтобы не уехал нолём), и
@@ -441,7 +449,10 @@ export function collectFormErrors(descriptors, fields) {
       return;
     }
 
-    const error = validateField(descriptor, field);
+    // тот же резолв алиаса, что и в buildField: валидация обязана смотреть
+    // на контрол, которым поле построено, иначе бывшее range-поле уезжает
+    // на хост без проверки диапазона
+    const error = validateField(resolveDescriptor(descriptor), field);
 
     if (error) {
       errors.push({

package/src/client/lib/pickActiveGame.js

@@ -0,0 +1,59 @@
+// Выбор активной игры из каталога мастера. Вынесено из client/main.js по той
+// же причине, что и socketDispatch.js: main.js исполняется при импорте, и
+// проверить ветвление внутри него нечем.
+//
+// Недоступная игра (manifest.compat.ok === false, этап 5 плана
+// plugin-forward-compat) в СПИСОК лобби попадает — с причиной, — но активной
+// быть не может: её плагин не загрузится, и вкладка встала бы на первой же
+// игре каталога.
+
+/**
+ * Доступна ли игра. Поле `compat` появляется у манифеста каталога мастера,
+ * только когда игра просит возможность, которой в этой сборке движка нет;
+ * манифест без него (все опубликованные до этапа 5) доступен по определению.
+ * @param {Object} manifest - GameManifest из каталога мастера.
+ * @returns {boolean}
+ */
+export function isGameAvailable(manifest) {
+  return manifest.compat?.ok !== false;
+}
+
+/**
+ * Активная игра вкладки.
+ *
+ * Обе ветки фильтруются одинаково: сохранённый выбор игры (`gameId`) тоже мог
+ * указывать на игру, ставшую недоступной после обновления движка, и брать её
+ * «раз уж попросили» значило бы падать там, где можно объяснить.
+ * @param {Array<Object>} manifests - Каталог мастера.
+ * @param {string} [gameId] - Сохранённый выбор игры (boot.gameId).
+ * @returns {Object|undefined} Манифест активной игры.
+ * @throws {Error} Если каталог непустой, но играбельной игры в нём нет —
+ *   с причиной по каждой строке.
+ */
+export function pickActiveGame(manifests, gameId) {
+  const active = gameId
+    ? manifests.find(
+        manifest => manifest.id === gameId && isGameAvailable(manifest),
+      )
+    : manifests.find(isGameAvailable);
+
+  if (active) {
+    return active;
+  }
+
+  // непустой каталог без единой играбельной строки — сказать это одной
+  // понятной фразой, а не отдать наверх первую попавшуюся и упасть в
+  // loadClientPlugin непрозрачной ошибкой
+  if (manifests.length) {
+    throw new Error(
+      'no playable game in the lobby catalog: ' +
+        manifests
+          .map(manifest => manifest.compat?.text ?? `"${manifest.id}"`)
+          .join('; '),
+    );
+  }
+
+  return undefined;
+}
+
+export default pickActiveGame;

package/src/client/lib/socketDispatch.js

@@ -0,0 +1,34 @@
+// Диспетчеризация входящего JSON-сообщения [portId, payload] по разрежённому
+// массиву обработчиков (client/main.js: socketMethods).
+//
+// Порт без обработчика — не исключение, а тишина (этап 3 плана
+// plugin-forward-compat). До этого `socketMethods[msg[0]](msg[1])` бросал
+// `TypeError: ... is not a function` и ронял обработку сообщения целиком:
+// получатель падал от того, что отправитель знает больше. Это не плагинная
+// ось (хост и клиент комнаты — один бандл движка, их расхождение ловится
+// codeVersion), но хрупкость ровно та же, и лечится она веткой по умолчанию.
+
+/**
+ * Отдаёт сообщение обработчику своего порта.
+ * @param {Array<Function>} methods - Обработчики по номеру порта.
+ * @param {Array} msg - Сообщение [portId, payload].
+ * @returns {boolean} Было ли сообщение обработано.
+ */
+export function dispatchSocketMessage(methods, msg) {
+  const port = msg?.[0];
+  const method = methods?.[port];
+
+  if (typeof method !== 'function') {
+    // console.debug, а не error: неизвестный порт — штатная встреча со
+    // «стороной, которая знает больше», а не дефект
+    console.debug(`client: no handler for port ${port} — message ignored`);
+
+    return false;
+  }
+
+  method(msg[1]);
+
+  return true;
+}
+
+export default dispatchSocketMessage;

package/src/client/main.js

@@ -26,7 +26,11 @@ 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 { buildForm, mergeRoomDefaults, bindLiveErrors } from './lib/formBuilder.js';
+import {
+  buildForm,
+  mergeRoomDefaults,
+  bindLiveErrors,
+} from './lib/formBuilder.js';
 import { normalizeAuthParams } from './lib/authParams.js';
 import { renderProjectLink } from './lib/footerLink.js';
 import { createGameActivator } from './lib/gameActivator.js';
@@ -36,6 +40,10 @@ import { ensureGameShell, ensureCanvas } from './views/gameShell.js';
 import { createContextTracker } from './lib/contextTracker.js';
 import { createLocalPlayer } from './lib/localPlayer.js';
 import { createAccolades } from './lib/accolades.js';
+import { dispatchSocketMessage } from './lib/socketDispatch.js';
+import { pickActiveGame, isGameAvailable } from './lib/pickActiveGame.js';
+import { readCoreAbi, dispatchCoreOp, ABI_UNKNOWN } from '../lib/coreAbi.js';
+import { ABI_OP_DEBUG_JSON } from '../config/abiOps.js';
 import { createDebugApi, debugLog, DEBUG_PREFIX } from './debug.js';
 import { buildClientCoreConfig } from '../lib/clientCoreConfig.js';
 import {
@@ -146,9 +154,8 @@ try {
       throw gamesManifest;
     }
 
-    activeGameManifest = boot.gameId
-      ? gamesManifest.find(manifest => manifest.id === boot.gameId)
-      : gamesManifest[0];
+    // недоступная игра активной быть не может (lib/pickActiveGame.js)
+    activeGameManifest = pickActiveGame(gamesManifest, boot.gameId);
   }
 
   if (!activeGameManifest) {
@@ -278,6 +285,12 @@ const socketMethods = []; // методы для обработки сокет-
 let clientCore = null;
 let wasm = null;
 
+// возможности загруженного клиентского ядра ({ abi, core, ops }) —
+// читаются один раз при создании ядра, а не в момент вызова. Ядро старше
+// самоописания даёт поколение 0 с пустым списком опкодов: это не ошибка,
+// а игра, собранная до появления механизма (И2 плана plugin-forward-compat)
+let clientCoreAbi = ABI_UNKNOWN;
+
 // сервис пула зависимостей: «эта сущность моя или чужая?». Ядро читается
 // геттером — оно создаётся позже пула сервисов (см. lib/localPlayer.js)
 const localPlayer = createLocalPlayer(() => clientCore);
@@ -312,6 +325,7 @@ socketMethods[PS_CONFIG_DATA] = async data => {
 
   clientCore = core;
   wasm = { memory };
+  clientCoreAbi = readCoreAbi(core, 'client core');
 
   // инициализация сущностей игры
   for (const entity of Object.keys(entitiesOnCanvas)) {
@@ -1130,8 +1144,7 @@ const RESYNC_AFTER_HIDDEN_MS = 3000;
 
 // вкладка могла быть скрыта уже в момент навешивания слушателя — события
 // 'hidden' тогда не будет, а пауза всё равно идёт
-let hiddenAt =
-  document.visibilityState === 'hidden' ? performance.now() : null;
+let hiddenAt = document.visibilityState === 'hidden' ? performance.now() : null;
 
 // обработчик видимости вкладки
 function handleVisibilityChange() {
@@ -1170,11 +1183,34 @@ function handleVisibilityChange() {
         }
       }
 
-      debugLog('clientCore', clientCore?.debug_json?.());
+      debugLog('clientCore', clientCoreDebug());
     }
   }
 }
 
+// дамп клиентского ядра: сначала опкод dispatch, затем замороженный метод.
+// Метод не удаляется никогда (И1), поэтому запасной путь остаётся навсегда:
+// ядро, собранное до появления dispatch, отдаёт дамп по-старому.
+// dispatchCoreOp — та же точка вызова, что у хостового GameCoreAdapter._op:
+// имя опкода читается из реестра, три исхода ответа различимы
+function clientCoreDebug() {
+  if (!clientCore) {
+    return undefined;
+  }
+
+  const { handled, bytes } = dispatchCoreOp(
+    clientCore,
+    clientCoreAbi,
+    ABI_OP_DEBUG_JSON,
+  );
+
+  if (handled && bytes !== null) {
+    return new TextDecoder().decode(bytes);
+  }
+
+  return clientCore.debug_json?.();
+}
+
 // единая точка управления рендер-циклом: Ticker.add дубликаты не отсеивает,
 // а добавить renderTick могут и runModules, и восстановление контекста
 function startRenderLoop() {
@@ -1270,10 +1306,9 @@ function handleMessage(data) {
     return;
   }
 
-  // JSON-сообщение [portId, payload]
-  const msg = unpacking(data);
-
-  socketMethods[msg[0]](msg[1]);
+  // JSON-сообщение [portId, payload]; порт без обработчика игнорируется, а
+  // не роняет обработку (lib/socketDispatch.js)
+  dispatchSocketMessage(socketMethods, unpacking(data));
 }
 
 // разрыв P2P: выход хоста = смерть комнаты (host-migration нет). Останавливаем
@@ -1373,7 +1408,9 @@ if (isDevBuild) {
     reportUrl: lobbyConfig.debugReportUrl,
   });
 
-  debugLog('window.__vimpDebug is available: dump, startRecording, stopRecording, divergence');
+  debugLog(
+    'window.__vimpDebug is available: dump, startRecording, stopRecording, divergence',
+  );
 }
 
 // WebRTC обязателен для P2P-игры. В Firefox RTCPeerConnection может
@@ -1904,7 +1941,9 @@ function populateRoomForm(manifest) {
 
 // каталог манифестов по id: форма и leaderboard селектора игр, а также
 // активация игры перед созданием комнаты и входом в чужую
-const gamesById = new Map(gamesManifest.map(manifest => [manifest.id, manifest]));
+const gamesById = new Map(
+  gamesManifest.map(manifest => [manifest.id, manifest]),
+);
 
 // ClientPlugin выбранной игры грузится в момент клика (создание комнаты /
 // вход в комнату), а не при смене селектора: просмотр каталога не должен
@@ -1965,9 +2004,17 @@ function populateGameSelect() {
 
   gamesManifest.forEach(manifest => {
     const option = document.createElement('option');
+    const available = isGameAvailable(manifest);
 
     option.value = manifest.id;
-    option.textContent = manifest.title;
+    // недоступная игра остаётся видимой (раньше мастер выкидывал её из
+    // каталога, и игрок видел пустое лобби без причины), но выбрать её
+    // нельзя: комнату по ней всё равно не поднять
+    option.textContent = available
+      ? manifest.title
+      : `${manifest.title} — unavailable`;
+    option.disabled = !available;
+    option.title = available ? '' : manifest.compat.text;
     gameSelect.appendChild(option);
   });
 

package/src/config/abiOps.js

@@ -0,0 +1,37 @@
+import { createRegistry } from '../lib/registry.js';
+
+// Реестр опкодов `dispatch` (этап 4 плана plugin-forward-compat). Таблица
+// экспортов wasm-ядра заморожена: символ, которого нет в уже опубликованном
+// `.wasm`, там не появится никогда, и никакой адаптер его не синтезирует.
+// Поэтому КАЖДАЯ будущая возможность ядра приезжает опкодом — строкой,
+// которую ядро либо понимает, либо нет, — а не новым методом.
+//
+// Реестр append-only (И1): опкод, который могла начать понимать игра,
+// существует вечно. Удаление опкода = удаление возможности, на которую
+// игра уже могла опереться.
+//
+// Форма записи: `payload`/`response` фиксируют кодировку байтов конкретного
+// опкода (сам `dispatch` их не знает — он возит сырые `Uint8Array`).
+// Пустой ответ ядра — «опкод не обработан»; `[0x00]` — «обработан, ответа
+// нет» (соглашение `abi::dispatch_result` в крейте).
+export const abiOps = createRegistry('abiOps', [
+  // курированный дамп мира ядра; дублирует замороженный метод debug_json,
+  // с которого началась проверка механизма (этап 4.6)
+  {
+    value: 'debug.json',
+    since: 4,
+    payload: 'none',
+    response: 'json',
+  },
+]);
+
+// плоский список активных опкодов — то, что вправе позвать движок
+export const ABI_OPS = abiOps.values();
+
+// Именованные константы вместо литералов в местах вызова: строка 'debug.json',
+// написанная руками у хоста и у клиента, обходила бы реестр молча — новый
+// опкод уехал бы в прод, не попав ни в слепок поверхности, ни в
+// CHANGELOG. Имя опкода читается ТОЛЬКО отсюда.
+export const ABI_OP_DEBUG_JSON = 'debug.json';
+
+export default abiOps;

package/src/config/clientServices.js

@@ -0,0 +1,27 @@
+import { createRegistry } from '../lib/registry.js';
+
+// Реестр движковых сервисов клиентского пула (этап 3 плана
+// plugin-forward-compat). Пул ими не исчерпывается: игра доливает туда свои
+// через ClientPlugin.hooks.services(core) — движок о них не знает ничего.
+//
+// Реестр append-only (И1): имя, которое игра написала в
+// componentDependencies, существует вечно. Ключевое поведение, на которое
+// опирается совместимость: пул отдаёт ЗАПРОШЕННОЕ, а не всё подряд
+// (client/providers/DependencyProvider.js), поэтому шестой сервис ничего не
+// требует от старых игр — они его не просят и не получают. Незнакомое имя —
+// не отказ загрузки, а undefined в парте; ловит его правило контракта C4.
+export const clientServices = createRegistry('clientServices', [
+  { value: 'renderer', since: 1 },
+  { value: 'soundManager', since: 1 },
+  // база ассетов пакета игры (`${assetsBase}img/...`)
+  { value: 'assetsBase', since: 3 },
+  // «свой ли это персонаж» (lib/localPlayer.js)
+  { value: 'localPlayer', since: 3 },
+  // места в глобальном топе (lib/accolades.js)
+  { value: 'accolades', since: 4 },
+]);
+
+// плоский список имён — то, чем правило C4 проверяет componentDependencies
+export const SERVICES = clientServices.values();
+
+export default clientServices;

package/src/config/opcodes.js

@@ -3,8 +3,17 @@
 // живут в Rust-ядре: packages/engine/core/src/snapshot.rs (pack) и packages/engine/core/src/client/unpack.rs.
 
 // версия контракта движок ↔ игра-плагин (GameManifest, HostPlugin,
-// ClientPlugin, Wasm Host ABI — docs/{en,ru}/plugin-api.md);
-// проверяется при загрузке плагинов; ломающие изменения контрактов → +1.
+// ClientPlugin, Wasm Host ABI — docs/{en,ru}/plugin-api.md).
+//
+// ЗАМОРОЖЕНО на 4. Больше не гейт совместимости и больше не бампается:
+// после этапов 1-4 плана plugin-forward-compat плагинная поверхность
+// append-only, и отвергать плагин за возраст стало не за что. Остаётся как
+// метка поколения контракта в манифестах и диагностике; удалять нельзя —
+// константу импортируют скрипты сборки всех уже существующих игр
+// (build-game-manifest.js) и правило контракта B2. Совместимость решается
+// переговорами о возможностях, см. lib/capabilities.js.
+//
+// История поколений (для чтения манифестов постарше):
 // v2: явная схема форм (roomForm/authSchema.params[].options — Form schema
 // в plugin-api.md), движок больше не выводит контролы из типа значения
 // v3: набор control сокращён до нативных элементов — 'select'|'text'|

package/src/config/wsports.js

@@ -1,3 +1,12 @@
+// Номера портов JSON-канала (docs/en/network.md). Реестр append-only, как и
+// остальные словари плагинной поверхности (этап 3 плана
+// plugin-forward-compat): номер НИКОГДА не переиспользуется и не
+// перенумеровывается — уже опубликованная сборка игры шлёт и слушает те
+// номера, что видела при сборке, и её dist больше никто не тронет.
+// Выведенный из эксплуатации порт остаётся в этом файле со своим номером и
+// пометкой `// retired in vN`, чтобы номер не был выдан повторно. За
+// механикой следит раздел `ports` слепка поверхности
+// (contract/surface.json): удаление имени или смена номера валит тест.
 export default {
   // порты получения данные от сервера
   server: {

package/src/devtools/contract/loadContext.js

@@ -2,6 +2,7 @@ import { access, readFile, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { ENGINE_API_VERSION } from '../../config/opcodes.js';
+import { createGameConfigView } from '../../lib/gameConfigView.js';
 
 // Сбор контекста статической проверки: по каталогу пакета игры собирается
 // всё, что удалось прочитать, и помечается недостающее. Ни одна неудача не
@@ -53,12 +54,30 @@ export async function loadContext(gameDir) {
   ctx.clientPlugin = await loadHalf(ctx, 'client', CLIENT_ENTRIES);
 
   ctx.gameConfig = ctx.hostPlugin?.gameConfig ?? null;
+  // то же представление, что построит движок при загрузке (этап 2 плана
+  // plugin-forward-compat): правило, которое спрашивает «что получится»,
+  // а не «что объявлено», обязано смотреть сюда — иначе оно краснеет на
+  // конфиге, который движок принимает. Невалидный конфиг о себе скажет
+  // правилом B3, поэтому здесь падение вырождается в исходный объект
+  ctx.gameConfigView = resolveConfigView(ctx);
   ctx.authSchema = ctx.hostPlugin?.authSchema ?? null;
   ctx.clientConfig = buildClientConfig(ctx);
 
   return ctx;
 }
 
+function resolveConfigView(ctx) {
+  if (!ctx.gameConfig) {
+    return null;
+  }
+
+  try {
+    return createGameConfigView(ctx.gameConfig, ctx.hostPlugin?.id);
+  } catch {
+    return ctx.gameConfig;
+  }
+}
+
 // Половина плагина: сначала исходник (он свежее сборки), при неудаче —
 // собранный entry из манифеста. Клиентский исходник в Node обычно не
 // импортируется вовсе (`import './game.css'` — расширение Vite, не Node),
@@ -156,7 +175,9 @@ async function readEngineCoreVersion() {
 // Разбор обязан совпадать — правьте обе или ни одной (см. тест
 // tests/scaffold/versions.test.js).
 export function parseCrateVersion(text) {
-  const section = text.split(/^\s*\[/m).find(part => part.startsWith('package]'));
+  const section = text
+    .split(/^\s*\[/m)
+    .find(part => part.startsWith('package]'));
 
   return section?.match(/^\s*version\s*=\s*"([^"]+)"/m)?.[1] ?? null;
 }
@@ -226,7 +247,9 @@ async function listFiles(root) {
       // симлинк-каталог (обычная dev-раскладка: dist/img -> ../assets/img)
       // у readdir не isDirectory(); без разыменования он попал бы в список
       // файлом, и правила ассетов дали бы ложный отказ
-      if (entry.isSymbolicLink() ? await isDirectory(full) : entry.isDirectory()) {
+      if (
+        entry.isSymbolicLink() ? await isDirectory(full) : entry.isDirectory()
+      ) {
         await walk(full, rel);
       } else {
         found.add(rel);