feat(vk): native share/copy, auto theme, friend-code deep link, home-bar safe area

Group B of the VK integration — the contour-verified follow-up to the launch+auth MVP:

- Share/copy inside the VK iframe go through VK Bridge: the friend-code invite shares via
  VKWebAppShare and copies via VKWebAppCopyText, since navigator.share is absent in the desktop
  iframe and navigator.clipboard is blocked there.
- The invite link is a VK Mini App direct link (vk.com/app<id>#f<code>) on VK instead of the
  Telegram link; the app id comes from vk_app_id in the launch params (no build arg needed). The
  recipient's launch routes the deep link from VK's `hash` launch query parameter.
- The app's "auto" theme follows the VK client's light/dark appearance (VKWebAppUpdateConfig),
  which the VK mobile webview's prefers-color-scheme does not track.
- The safe-area CSS vars default to env(safe-area-inset-*), so the VK mobile layout clears the
  home bar (and Capacitor/PWA too); Telegram still overrides them from its SDK.

vk.ts adds vkAppId/vkStartParam/vkShare/vkCopyText/vkOnScheme. Verified: svelte-check, 347 unit
(+ vkAppId/vkStartParam/vkShareLink), build, bundle-gate. The VK-Bridge behaviours need the live
contour (not reproducible headless).

.claude/vk-games-integration.md

@@ -77,14 +77,25 @@ incl. the `%2C` comma case for `vk_access_token_settings`).
 - `VKWebAppGetLaunchParams` — parsed `vk_*` **without** `sign` (so NOT usable for our server
   verification — read `window.location.search` instead, which carries `sign`).
 - `VKWebAppGetAuthToken` — OAuth access token for VK API calls (only if we ever call VK API).
-- `VKWebAppShare` — native share dialog (deferred).
-- `VKWebAppSetViewSettings` / `VKWebAppSetSwipeSettings` — viewport / swipe-back (mobile).
-- `VKWebAppUpdateConfig` (subscribe) — light/dark scheme + theme changes.
+- `VKWebAppShare` — native share dialog (the friend-code invite uses it; `navigator.share` is absent
+  in the desktop VK iframe). **Used.**
+- `VKWebAppCopyText` — clipboard copy that works inside the VK iframe, where `navigator.clipboard` is
+  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).
 
 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
 it **lazily** so the pure URL helpers stay node-test-importable.
 
+**Deep links** (direct-link launch): `https://vk.com/app<id>#<payload>` forwards everything after the
+`#` to the app as the **`hash` launch query parameter** (it is also in `location.hash`, but that
+collides with our hash router, so read the `hash` query param). `?` query strings are NOT supported
+for VK direct links. The friend-code invite is built as `vk.com/app<id>#f<code>` — the app id comes
+from `vk_app_id` in the launch params (no `VITE_VK_APP_ID` needed) — and read back via `vkStartParam`.
+
 ## 5. Test mode (to verify before moderation)
 
 1. App already registered (we have the App ID).
@@ -138,15 +149,17 @@ without VK-specific code. Theme/viewport fine-tuning is best verified live in th
 - **Backend**: `internal/account` `KindVK` + `ProvisionVK`/`vkSeed` + `confirmed` for platform
   kinds; `internal/server/handlers_auth.go` `handleVKAuth` + route; migration
   `00005_vk_identity.sql` (widen `identities_kind_chk` to include `'vk'`, expand-contract).
-- **UI**: `src/lib/vk.ts` (`onVKPath`/`vkLaunchParams`/`insideVK`/`vkInit`/`vkUserName`),
-  `app.svelte.ts` `bootVK` + the `/vk/` dispatch branch + shared `retryMiniAppBoot`,
-  `codec.ts` `encodeVKLogin`, `transport.ts`/`client.ts`/`mock/client.ts` `authVK`.
+- **UI**: `src/lib/vk.ts` (`onVKPath`/`vkLaunchParams`/`insideVK`/`vkInit`/`vkUserName` plus `vkAppId`/
+  `vkStartParam`/`vkShare`/`vkCopyText`/`vkOnScheme`), `app.svelte.ts` `bootVK` (+ deep-link routing
+  and VK scheme→theme) + the `/vk/` dispatch branch + shared `retryMiniAppBoot`, `codec.ts`
+  `encodeVKLogin`, `transport.ts`/`client.ts`/`mock/client.ts` `authVK`, `deeplink.ts` `vkShareLink`,
+  `Friends.svelte` (VK share/copy), `app.css` `--tg-safe-*` defaulting to `env(safe-area-inset-*)`.
 - **Edge/deploy**: `deploy/caddy/Caddyfile` `/vk` path; `GATEWAY_VK_APP_SECRET` in
   `docker-compose.yml` + `.env.example` + `ci.yaml` (`TEST_…` secret) + `prod-deploy.yaml`
   (`PROD_…` secret, deploy-main).
-- **Deferred** (not in the test-mode MVP): `VKWebAppShare`, deep-links (`vk_ref`/startapp),
-  VK theme/viewport forcing, `VITE_VK_APP_ID` build arg, payments, account-linking a vk identity
-  to an existing account.
+- **Deferred**: payments (VK Pay / votes), native (Capacitor) VK, account-linking a vk identity to an
+  existing account, VK push. (Done after the launch+auth MVP — Group B: native share + clipboard via
+  the bridge, the friend-code deep link, the auto-theme follow, and the home-bar safe area.)
 
 ## Sources
 

docs/FUNCTIONAL.md

@@ -125,7 +125,7 @@ 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 deep link that opens it directly): the inviter chooses the
+is shareable as a Telegram or VK deep link that opens it directly): 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

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

ui/src/app.css

@@ -46,14 +46,16 @@
   /* Height Telegram's native nav overlays at the top in fullscreen; set from the SDK's
      content-safe-area inset, 0 elsewhere. */
   --tg-content-top: 0px;
-  /* Telegram device safe-area top (the notch); TG's own nav controls sit between it and
-     --tg-content-top, so the in-app header aligns to that band, 0 elsewhere. */
-  --tg-safe-top: 0px;
-  /* Telegram device safe-area bottom / sides (home indicator; landscape notch), 0 elsewhere —
-     the screen pads its bottom and left/right edges by these so content clears the cut-outs. */
-  --tg-safe-bottom: 0px;
-  --tg-safe-left: 0px;
-  --tg-safe-right: 0px;
+  /* Device safe-area top (the notch); inside Telegram TG's own nav controls sit between it and
+     --tg-content-top, so the in-app header aligns to that band. Inside Telegram these are set from
+     the SDK (lib/app.svelte.ts); elsewhere they fall back to the CSS env() safe area, so a VK Mini
+     App / Capacitor / PWA webview clears the device cut-outs too (a plain browser tab reports 0). */
+  --tg-safe-top: env(safe-area-inset-top, 0px);
+  /* Device safe-area bottom / sides (home indicator; landscape notch) — the screen pads its bottom
+     and left/right edges by these so content clears the cut-outs (e.g. the VK mobile home bar). */
+  --tg-safe-bottom: env(safe-area-inset-bottom, 0px);
+  --tg-safe-left: env(safe-area-inset-left, 0px);
+  --tg-safe-right: env(safe-area-inset-right, 0px);
   --font: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial,
     "Noto Sans", "Liberation Sans", sans-serif;
   --shadow: 0 1px 2px rgba(0, 0, 0, 0.08), 0 6px 16px rgba(0, 0, 0, 0.06);

ui/src/lib/app.svelte.ts

@@ -32,7 +32,7 @@ import {
   telegramCloudGet,
   telegramCloudSet,
 } from './telegram';
-import { onVKPath, insideVK, vkInit, vkLaunchParams, vkUserName } from './vk';
+import { onVKPath, insideVK, vkInit, vkLaunchParams, vkUserName, vkStartParam, vkOnScheme } from './vk';
 import { CLOUD_PREFS_KEY, decodeClientPrefs, encodeClientPrefs } from './cloudprefs';
 import { parseStartParam } from './deeplink';
 import { clearSession, loadPrefs, loadSession, saveSession, savePrefs } from './session';
@@ -670,6 +670,11 @@ export async function bootstrap(): Promise<void> {
   // VKWebAppGetUserInfo, since VK omits it from the signed params. The /vk/ entry opened outside VK
   // (no signed params — e.g. a developer hitting the URL directly) falls through to the web flow.
   if (onVKPath() && insideVK()) {
+    // Follow the VK client's light/dark appearance while the user keeps the app's "auto" theme (the
+    // VK mobile webview's prefers-color-scheme does not track it).
+    void vkOnScheme((scheme) => {
+      if (app.theme === 'auto') applyTheme(scheme);
+    });
     await vkInit();
     await bootVK();
     app.ready = true;
@@ -737,6 +742,8 @@ async function bootVK(): Promise<void> {
   for (let attempt = 0; ; attempt++) {
     try {
       await adoptSession(await gateway.authVK(params, displayName));
+      // A VK direct-link deep link (vk.com/app<id>#<param>) rides in as the `hash` launch param.
+      if (!app.blocked) await routeStartParam(vkStartParam());
       app.bootError = false;
       return;
     } catch (err) {

ui/src/lib/deeplink.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { botUsername, friendCodeParam, gameParam, invitationParam, parseStartParam, shareLink } from './deeplink';
+import { botUsername, friendCodeParam, gameParam, invitationParam, parseStartParam, shareLink, vkShareLink } from './deeplink';
 
 describe('parseStartParam', () => {
   it('classifies game / invitation / friend code', () => {
@@ -37,6 +37,20 @@ describe('shareLink', () => {
   });
 });
 
+describe('vkShareLink', () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it('returns null outside a VK launch (no vk_app_id)', () => {
+    vi.stubGlobal('location', { search: '' });
+    expect(vkShareLink('f123456')).toBeNull();
+  });
+
+  it('wraps the payload in a vk.com/app direct link after the hash', () => {
+    vi.stubGlobal('location', { search: '?vk_app_id=6736218&vk_user_id=1&sign=x' });
+    expect(vkShareLink('f123456')).toBe('https://vk.com/app6736218#f123456');
+  });
+});
+
 describe('botUsername', () => {
   afterEach(() => vi.unstubAllEnvs());
 

ui/src/lib/deeplink.ts

@@ -6,6 +6,8 @@
 //   f<6-digit code>     redeem that friend code
 // An empty or unrecognised parameter opens the lobby.
 
+import { vkAppId } from './vk';
+
 export type DeepLink =
   | { kind: 'lobby' }
   | { kind: 'game'; id: string }
@@ -74,3 +76,16 @@ export function shareLink(param: string): string | null {
   const sep = base.includes('?') ? '&' : '?';
   return `${base}${sep}startapp=${encodeURIComponent(param)}`;
 }
+
+/**
+ * vkShareLink wraps a deep-link start parameter in a VK Mini App direct link
+ * (https://vk.com/app<id>#<param>). VK forwards everything after the '#' to the app as the `hash`
+ * launch parameter (read back by vk.ts vkStartParam); a query string ('?') is not supported for VK
+ * direct links. Returns null when the VK app id is unknown (outside a VK launch), so the caller
+ * falls back to the Telegram/web link.
+ */
+export function vkShareLink(param: string): string | null {
+  const id = vkAppId();
+  if (!id) return null;
+  return `https://vk.com/app${id}#${param}`;
+}

ui/src/lib/vk.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { insideVK, onVKPath, vkLaunchParams } from './vk';
+import { insideVK, onVKPath, vkAppId, vkLaunchParams, vkStartParam } from './vk';
 
 describe('vk launch detection', () => {
   afterEach(() => vi.unstubAllGlobals());
@@ -29,3 +29,23 @@ describe('vk launch detection', () => {
     expect(insideVK()).toBe(false);
   });
 });
+
+describe('vk launch params', () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it('reads the VK app id from the launch query', () => {
+    vi.stubGlobal('location', { pathname: '/vk/', search: '?vk_app_id=6736218&sign=x' });
+    expect(vkAppId()).toBe('6736218');
+  });
+
+  it('reads the direct-link deep-link payload from the hash query param', () => {
+    vi.stubGlobal('location', { pathname: '/vk/', search: '?vk_user_id=1&sign=x&hash=f123456' });
+    expect(vkStartParam()).toBe('f123456');
+  });
+
+  it('returns empty app id / start param when absent', () => {
+    vi.stubGlobal('location', { pathname: '/vk/', search: '?vk_user_id=1&sign=x' });
+    expect(vkAppId()).toBe('');
+    expect(vkStartParam()).toBe('');
+  });
+});

ui/src/lib/vk.ts

@@ -64,3 +64,70 @@ export async function vkUserName(): Promise<string> {
     return '';
   }
 }
+
+/**
+ * vkAppId returns the launching VK app id (vk_app_id) from the signed launch parameters in the URL —
+ * so the app can build its own vk.com/app<id> links without a VK API call — or '' outside a VK launch.
+ */
+export function vkAppId(): string {
+  if (typeof location === 'undefined') return '';
+  return new URLSearchParams(location.search.replace(/^\?/, '')).get('vk_app_id') ?? '';
+}
+
+/**
+ * vkStartParam returns the VK direct-link deep-link payload. VK passes everything after the '#' in a
+ * vk.com/app<id>#<payload> link to the app as the `hash` query parameter (it is also in location.hash,
+ * but that collides with the app's hash router, so the query parameter is the safe source). Empty when
+ * the launch carried no deep link.
+ */
+export function vkStartParam(): string {
+  if (typeof location === 'undefined') return '';
+  return new URLSearchParams(location.search.replace(/^\?/, '')).get('hash') ?? '';
+}
+
+/**
+ * vkShare opens VK's native share dialog for link (VKWebAppShare) — the in-iframe replacement for
+ * navigator.share, which is unavailable in the desktop VK iframe. Resolves true when the share was
+ * handled, false on any failure or outside VK.
+ */
+export async function vkShare(link: string): Promise<boolean> {
+  try {
+    await (await bridge()).send('VKWebAppShare', { link });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * vkCopyText copies text to the clipboard via VKWebAppCopyText — which works inside the VK iframe,
+ * where navigator.clipboard is blocked. Resolves true on success, false on any failure or outside VK.
+ */
+export async function vkCopyText(text: string): Promise<boolean> {
+  try {
+    await (await bridge()).send('VKWebAppCopyText', { text });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * vkOnScheme subscribes to VK's appearance (VKWebAppUpdateConfig) and calls handler with the mapped
+ * 'light' | 'dark' scheme on launch and whenever the user switches the VK client theme — so the app's
+ * "auto" theme can follow the VK client instead of the (often wrong) webview prefers-color-scheme.
+ * A no-op outside VK.
+ */
+export async function vkOnScheme(handler: (scheme: 'light' | 'dark') => void): Promise<void> {
+  try {
+    const b = await bridge();
+    b.subscribe((e) => {
+      const detail = (e as { detail?: { type?: string; data?: { scheme?: string; appearance?: string } } }).detail;
+      if (detail?.type !== 'VKWebAppUpdateConfig') return;
+      const scheme = detail.data?.scheme ?? detail.data?.appearance ?? '';
+      handler(/dark|space_gray/i.test(scheme) ? 'dark' : 'light');
+    });
+  } catch {
+    // Outside VK / bridge unavailable: leave the app on its own theme.
+  }
+}

ui/src/screens/Friends.svelte

@@ -6,8 +6,9 @@
   import { gateway } from '../lib/gateway';
   import { GatewayError } from '../lib/client';
   import { t } from '../lib/i18n/index.svelte';
-  import { friendCodeParam, shareLink } from '../lib/deeplink';
+  import { friendCodeParam, shareLink, vkShareLink } from '../lib/deeplink';
   import { insideTelegram, shareTelegramLink, telegramDialogsAvailable, telegramShowConfirm } from '../lib/telegram';
+  import { insideVK, vkCopyText, vkShare } from '../lib/vk';
   import type { AccountRef, FriendCode, RobotBlockEntry } from '../lib/model';
 
   let friends = $state<AccountRef[]>([]);
@@ -140,6 +141,11 @@
 
   async function copyCode() {
     if (!code) return;
+    // Inside the VK iframe navigator.clipboard is blocked, so copy via VK Bridge there.
+    if (insideVK()) {
+      if (await vkCopyText(code.code)) showToast(t('friends.codeCopied'));
+      return;
+    }
     try {
       await navigator.clipboard.writeText(code.code);
       showToast(t('friends.codeCopied'));
@@ -153,6 +159,13 @@
   // copies the link to the clipboard.
   async function shareInvite(url: string) {
     const text = t('friends.inviteText');
+    // Inside VK navigator.share is absent (desktop iframe) and the clipboard is blocked: share via VK
+    // Bridge, falling back to a VK-Bridge clipboard copy if the share is dismissed or unavailable.
+    if (insideVK()) {
+      if (await vkShare(url)) return;
+      if (await vkCopyText(url)) showToast(t('friends.linkCopied'));
+      return;
+    }
     if (shareTelegramLink(url, text)) return;
     if (typeof navigator !== 'undefined' && navigator.share) {
       try {
@@ -188,7 +201,8 @@
         <button class="btn" onclick={redeem} disabled={!connection.online}>{t('friends.redeem')}</button>
       </div>
       {#if code}
-        {@const tg = shareLink(friendCodeParam(code.code))}
+        {@const sharePayload = friendCodeParam(code.code)}
+        {@const shareUrl = insideVK() ? vkShareLink(sharePayload) : shareLink(sharePayload)}
         <div class="code" data-testid="friend-code">
           <div class="coderow">
             <button class="codeval" onclick={copyCode}>{code.code}</button>
@@ -197,8 +211,8 @@
           <span class="codehint">
             {t('friends.codeHint')} · {t('friends.codeExpires', { time: codeTime(code.expiresAtUnix) })}
           </span>
-          {#if tg}
-            <button type="button" class="link" onclick={() => shareInvite(tg)}>{t('friends.shareTelegram')}</button>
+          {#if shareUrl}
+            <button type="button" class="link" onclick={() => shareInvite(shareUrl)}>{t('friends.shareTelegram')}</button>
           {/if}
         </div>
       {:else}