Merge pull request 'docs: sync FUNCTIONAL/UI_DESIGN/.claude with the shipped VK + landscape behaviour (#140-#142 follow-up)' (#145) from fix/vk-docs-deeplink-and-pan into development

.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
@@ -125,7 +127,8 @@ and any incidental perpendicular words are ignored and not scored — while on i
 standard Scrabble. English games are always standard and show no such toggle. In auto-match
 the choice joins the pairing key, so a player only meets opponents who picked the same rule. Friend games (2–4) are
 formed by inviting players from the friend list (an invitation, like a friend code,
-is shareable as a Telegram or VK deep link that opens it directly): the inviter chooses the
+is shareable as a Telegram deep link that opens it directly — on VK, which forwards no payload to the
+Mini App, the link only opens the app and the recipient enters the copied code by hand): the inviter chooses the
 settings and the game starts once every invitee has accepted — any decline cancels it, and an unanswered invitation
 expires after seven days.
 

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). Рядом с основным может работать отдельный опциональный
@@ -131,7 +133,8 @@ _Вход сейчас только через провайдера, поэто
 показывают. В авто-подборе выбор входит в ключ подбора, поэтому игрок сводится только с теми,
 кто выбрал то же правило. Игры с друзьями (2–4)
 формируются приглашением игроков из списка друзей (приглашение, как и код друга,
-можно отправить deep-link'ом в Telegram или VK, который откроет его сразу): инициатор
+можно отправить deep-link'ом в Telegram, который откроет его сразу — на VK, который не передаёт Mini App
+никакой нагрузки, ссылка лишь открывает приложение, а скопированный код получатель вводит вручную): инициатор
 выбирает настройки, и партия стартует, когда приняли все приглашённые — любой отказ отменяет приглашение, а без
 ответа приглашение протухает через семь дней.
 

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
 
@@ -137,7 +144,10 @@ dismisses as soon as the lobby is ready. The pure layout and timing live in `lib
   the first time. A **swipe down on the zoom-out board** opens the history, but only when the
   board is scrolled to its top so it never fights the stage's own vertical scroll (the conflict
   that once retired this gesture) — and it is suppressed on the zoomed board, where the
-  one-finger drag pans. History also opens on a **tap of the score bar** and closes on a tap or
+  one-finger drag pans (and on desktop / the landscape iframe, where a mouse cannot drag-scroll the
+  viewport natively, a **drag-to-pan** handler moves the zoomed board instead — active only while
+  zoomed, off pending tiles, past a small threshold, swallowing the trailing click). History also
+  opens on a **tap of the score bar** and closes on a tap or
   an **upward swipe** of the then-inert board (below). A **hint** auto-zooms centred on the
   hint's placement, not
   the top-left.