From 637503f32dde1e7a82d9862e476e7f2bc7a18819 Mon Sep 17 00:00:00 2001
From: Valentin Popov <valentin@popov.link>
Date: Fri, 30 Oct 2026 15:48:55 +0400
Subject: docs(ui): describe native menu font resource bindings

---
 docs/appendices/ui-shell.md | 60 +++++++++++++++++++++++++++++++++++++++------
 1 file changed, 53 insertions(+), 7 deletions(-)

(limited to 'docs/appendices/ui-shell.md')

diff --git a/docs/appendices/ui-shell.md b/docs/appendices/ui-shell.md
index d236e14..7a5b7d1 100644
--- a/docs/appendices/ui-shell.md
+++ b/docs/appendices/ui-shell.md
@@ -26,10 +26,56 @@ Win32 messages
 `sprites.lib` и `Palettes.lib`. Конфигурации задают controls/resources/cursor,
 overlays и HQ; `TextRes.cfg` связывает символические ключи с текстом.
 
-`gamefont.rlb` содержит две LZSS-записи (`0x040`), `sprites.lib` — 24 записи
-raw Deflate (`0x100`). `sprites.lib::INTERF8.TEX` использует известный
-`deflate_eof_plus_one` quirk. UI обязан пользоваться общим RsLi reader, а не
-отдельной похожей распаковкой.
+В demo `gamefont.rlb` содержит две LZSS-записи (`0x040`); `sprites.lib`
+содержит 24 записи raw Deflate (`0x100`) и известный `deflate_eof_plus_one`
+quirk для `INTERF8.TEX`. В полной GOG-сборке меню отдельно связывает
+`ui/menu_resources.cfg` с `ui/font.lib`, архивом NRes. Поэтому `gamefont.rlb`
+не задаёт единственный путь шрифта. Оба контейнера уже читаются общими
+[RsLi](../reference/rsli.md)- и [NRes](../reference/nres.md)-readers проекта;
+будущая UI-подсистема должна пользоваться ими, а не добавлять свою распаковку.
+
+В `menu_resources.cfg` ресурс `fonts` указывает `ui\\font.lib` с `libtype=multi`
+и `type=2`; это поля CFG, а не FourCC записей NRes. У девяти записей
+`font.lib` `type_id` равен `0x544E4F46` (`FONT`). Значение подстановки в
+`font-substitute` — строковое имя: этот CFG alias (`MENU_FONT` или `GAME_FONT`)
+связывает роль шрифта с его именем, но сам не является именем записи архива.
+Числовые ссылки находятся отдельно, в объекте `fonts`. В проверенной паре CFG и
+архива эти ссылки совпадают с исходными порядковыми номерами записей NRes
+(`EntryId`), а не с `sort_index`:
+
+| Размер CFG | Строковый alias `font-substitute` | Ссылка `fonts` | `EntryId` и запись NRes |
+| --- | --- | --- | --- |
+| `640x480` | `MENU_FONT` | `8` | `8`, `mf_640.tft` |
+| `640x480` | `GAME_FONT` | `6` | `6`, `gf_640.tft` |
+| `800x600` | `MENU_FONT` | `5` | `5`, `mf_800.tft` |
+| `800x600` | `GAME_FONT` | `3` | `3`, `gf_800.tft` |
+| `1024x768` | `MENU_FONT` | `2` | `2`, `mf_1024.tft` |
+| `1024x768` | `GAME_FONT` | `0` | `0`, `gf_1024.tft` |
+
+Пример из этой CFG: `font-substitute` связывает `MENU_FONT` со строкой
+`MENU_FONT_1024x768`, а объект `fonts` связывает уже это имя с числом `2`.
+Такое сопоставление относится только к этой конфигурации и архиву, а не является
+универсальным правилом native selector. Строка `1024x768` не доказывает выбор
+этого варианта при фактическом экране `1280x1024`.
+
+Проверены оригинальные `menu_resources.cfg` (SHA-256
+`508C3783EAF112023E46BF4617424FBB57C393BCEF328CE1B925549B0069EF97`) и
+`font.lib` (440392 bytes, SHA-256
+`E4AF5D1F0BF0464574DE654DE378766090681F610705CE53539DF9041E045D1C`).
+Шесть сопоставленных payload начинаются с `Tfnt`; это подтверждает сигнатуру
+данных, но не значение последующих полей.
+
+Связка подтверждена и в оригинальном коде. В `iron3d.dll` SHA-256
+`D1DC4EA8535E2069B0A05C9E8BE2724DD438BA44CCA7A83007D8B2E50F9E35FA` shell
+читает `shell_ctrls.cfg` в RVA `0x7410`, а инициализация в `0x78c0` читает и
+регистрирует `menu_resources.cfg` в слоте `0` ResourceManager. `services.dll` SHA-256
+`D3619DEEB4D598B16099E0263E15F9C3213F0FAA7208DC093328CFBA93FDC0EA`, RVA
+`0x92a0`, разбирает `font-substitute`, размерные значения и запись ресурса
+`type=2`. Затем `iron3d.dll` запрашивает `MENU_FONT` в RVA `0x1eb20`, ищет ресурс
+в `0x1ed06` и разыменовывает результат в `0x1ed3e`; прямая x86-трасса на
+последнем участке подтвердила ненулевой объект. Это подтверждает получение
+реального font-объекта, но не конкретной NRes-записи при `1280x1024`, её
+отрисовку или паритет шрифтов.
 
 Ключ ресурса, legacy path, локализованный текст и исходные bytes — четыре
 разные идентичности. Archive keys остаются ASCII-casefold; `TextRes.cfg`,
@@ -50,9 +96,9 @@ viewport, scale/letterbox policy, mouse-to-layout transform, clipping и
 z-order. Cursor, sprite и hit-test обязаны применять одно преобразование.
 
 Font contract включает glyph image, advance, bearing/offset, line height и
-fallback glyph. Binary glyph metrics `gamefont.rlb` пока не восстановлены:
-payload читается lossless через RsLi, а семантика устанавливается по consumer
-trace.
+fallback glyph. Содержимое `gamefont.rlb` и `Tfnt` payload записей `.tft`
+сохраняется без потери bytes через общие readers (`RsLi` и `NRes`), но семантика
+метрик и глифов ещё не восстановлена по consumer trace.
 
 Нормализованное событие проходит modal widget, затем shell command map; лишь
 разрешённая gameplay-команда превращается в World3D manual event. Held state и
-- 
cgit v1.2.3