.claude/vk-games-integration.md

@@ -83,8 +83,10 @@ incl. the `%2C` comma case for `vk_access_token_settings`).
   blocked. **Used** as the copy-code / copy-link path.
 - `VKWebAppUpdateConfig` (subscribe) — light/dark scheme; the app follows it while the theme pref is
   "auto" (the VK webview's prefers-color-scheme does not track it). **Used.**
-- `VKWebAppSetViewSettings` / `VKWebAppSetSwipeSettings` — viewport / swipe-back (mobile); not used —
-  the bottom home-bar safe area is handled by CSS `env(safe-area-inset-*)` (viewport-fit=cover).
+- `VKWebAppSetViewSettings` / `VKWebAppSetSwipeSettings` — viewport / swipe-back (mobile); not used.
+- `VKWebAppUpdateInsets` (+ `VKWebAppUpdateConfig`) — device safe-area insets; the app **max'es** them
+  with CSS `env(safe-area-inset-*)` (viewport-fit=cover) so the bottom home bar is cleared. The bridge
+  value is needed on Android, where the VK webview exposes no `env()` inset. **Used.**
 
 The bridge talks to the embedding VK client over postMessage; it is NOT an external fetch, so
 it has no telegram.org-style load-hang risk. The SDK reads browser globals at import — we import

docs/FUNCTIONAL.md

@@ -38,7 +38,9 @@ deployment), the Mini App retries quietly and then shows a small "couldn't load"
 A **VK Mini App** launch works the same way: it authenticates from VK's signed launch parameters
 (verified by the gateway), and on first contact seeds the new account's interface language from
 `vk_language` and its display name from the VK profile (read on the client, since VK does not put
-the name in the signed launch). The same quiet-retry "couldn't load" screen applies inside VK.
+the name in the signed launch). While the theme preference is "auto" the app follows the VK
+client's light/dark scheme, and the layout clears the VK mobile home bar. The same quiet-retry
+"couldn't load" screen applies inside VK.
 Telegram runs a **single bot**: every player uses
 the same bot, and all of its chat and out-of-app notifications are written in the
 player's own **interface language** (en/ru). A separate optional **promo bot** can run alongside the

docs/FUNCTIONAL_ru.md

@@ -40,7 +40,9 @@ Mini App** авторизует по подписанным `initData` плат
 Telegram не место. Запуск **VK Mini App** работает так же: авторизует по подписанным
 launch-параметрам VK (их проверяет gateway), и при первом контакте задаёт язык интерфейса
 нового аккаунта по `vk_language`, а отображаемое имя — по профилю VK (читается на клиенте,
-так как VK не кладёт имя в подписанный запуск). Тот же экран тихого повтора «не удалось
+так как VK не кладёт имя в подписанный запуск). Пока тема в режиме «авто», приложение следует
+светлой/тёмной схеме VK-клиента, а раскладка обходит нижнюю home-bar VK на мобильных. Тот же экран
+тихого повтора «не удалось
 загрузить» действует и внутри VK. Telegram держит **единого бота**: все игроки пользуются одним
 и тем же ботом, а весь его чат и внеприложенческие уведомления пишутся на **языке
 интерфейса** самого игрока (en/ru). Рядом с основным может работать отдельный опциональный

docs/UI_DESIGN.md

@@ -113,6 +113,13 @@ dismisses as soon as the lobby is ready. The pure layout and timing live in `lib
   by a background suspend reconnects silently on return — the connection banner is
   suppressed while hidden and for a short grace after resume (visibilitychange +
   pageshow/pagehide + Telegram `activated`/`deactivated`).
+- **VK integration** (`lib/vk.ts`): inside the VK Mini App the **auto** theme follows the VK
+  client's light/dark (`VKWebAppUpdateConfig`), as the VK webview's `prefers-color-scheme` does not
+  track it; explicit light/dark prefs still win. The device safe-area comes from CSS
+  `env(safe-area-inset-*)` (the meta already sets `viewport-fit=cover`) **max'd** with the VK bridge
+  insets (`VKWebAppUpdateInsets`, needed on Android, where the VK webview exposes no `env()` inset),
+  so the layout clears the VK home bar. Share and copy route through the bridge (`VKWebAppShare` /
+  `VKWebAppCopyText`) because `navigator.share` / `clipboard` are absent in the desktop VK iframe.
 
 ## Tiles & board