fix(vk): friend-code link as ?hash, Android safe-area via bridge insets, landscape home-bar colour

Contour review of the VK Bridge group:

- #6 invite link: VK's documented '#' direct-link payload is eaten by the vk.com SPA before it
  reaches the app, so the friend-code link now carries the payload as a query param
  (vk.com/app<id>?hash=f<code>); the recipient already reads the `hash` query param (vkStartParam).
  (Whether VK forwards the '?' through to the iframe is being confirmed on the contour.)
- #8 Android: the VK mobile webview does not surface the home-bar inset via CSS env() (config
  insets are iOS-only), so subscribe to the bridge insets (VKWebAppUpdateConfig + VKWebAppUpdateInsets)
  and set --tg-safe-* to max(env(), the VK value).
- #8 landscape colour: the home-indicator strip was the (grey) page background because the two-pane
  landscape game has no bottom bar. The left-panel controls bar now paints its own chrome into the
  inset (Screen gains a selfInset flag that drops the shell's detached padding strip), and the
  game-land runs flush to the edge.

Verified: svelte-check, 347 unit, build, bundle-gate; the landscape safe-area painting reproduced in
the mock (controls bar + board reach the edge, strip takes the bar colour). The VK-Bridge / VK launch
behaviours (Android insets, the ?hash forward) need the live contour.

ui/src/lib/app.svelte.ts

@@ -32,7 +32,7 @@ import {
   telegramCloudGet,
   telegramCloudSet,
 } from './telegram';
-import { onVKPath, insideVK, vkInit, vkLaunchParams, vkUserName, vkStartParam, vkOnScheme } from './vk';
+import { onVKPath, insideVK, vkInit, vkLaunchParams, vkUserName, vkStartParam, vkOnScheme, vkOnInsets } from './vk';
 import { CLOUD_PREFS_KEY, decodeClientPrefs, encodeClientPrefs } from './cloudprefs';
 import { parseStartParam } from './deeplink';
 import { clearSession, loadPrefs, loadSession, saveSession, savePrefs } from './session';
@@ -675,6 +675,15 @@ export async function bootstrap(): Promise<void> {
     void vkOnScheme((scheme) => {
       if (app.theme === 'auto') applyTheme(scheme);
     });
+    // Clear the device safe area from VK's insets — the VK mobile webview does not surface them via
+    // CSS env() (notably the Android home bar). max() keeps whichever of env() / the VK value is real.
+    void vkOnInsets((i) => {
+      const root = document.documentElement;
+      root.style.setProperty('--tg-safe-top', `max(env(safe-area-inset-top, 0px), ${i.top}px)`);
+      root.style.setProperty('--tg-safe-bottom', `max(env(safe-area-inset-bottom, 0px), ${i.bottom}px)`);
+      root.style.setProperty('--tg-safe-left', `max(env(safe-area-inset-left, 0px), ${i.left}px)`);
+      root.style.setProperty('--tg-safe-right', `max(env(safe-area-inset-right, 0px), ${i.right}px)`);
+    });
     await vkInit();
     await bootVK();
     app.ready = true;

ui/src/lib/deeplink.test.ts

@@ -45,9 +45,9 @@ describe('vkShareLink', () => {
     expect(vkShareLink('f123456')).toBeNull();
   });
 
-  it('wraps the payload in a vk.com/app direct link after the hash', () => {
+  it('wraps the payload in a vk.com/app link as the hash query param', () => {
     vi.stubGlobal('location', { search: '?vk_app_id=6736218&vk_user_id=1&sign=x' });
-    expect(vkShareLink('f123456')).toBe('https://vk.com/app6736218#f123456');
+    expect(vkShareLink('f123456')).toBe('https://vk.com/app6736218?hash=f123456');
   });
 });
 

ui/src/lib/deeplink.ts

@@ -78,14 +78,14 @@ export function shareLink(param: string): string | null {
 }
 
 /**
- * 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.
+ * vkShareLink wraps a deep-link start parameter in a VK Mini App link
+ * (https://vk.com/app<id>?hash=<param>), read back by vk.ts vkStartParam (the `hash` query param).
+ * VK's documented '#' direct-link form is consumed by the vk.com SPA before it reaches the app, so
+ * we pass the payload as a query parameter instead. 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}`;
+  return `https://vk.com/app${id}?hash=${encodeURIComponent(param)}`;
 }

ui/src/lib/vk.ts

@@ -131,3 +131,32 @@ export async function vkOnScheme(handler: (scheme: 'light' | 'dark') => void): P
     // Outside VK / bridge unavailable: leave the app on its own theme.
   }
 }
+
+/** VKInsets is the device safe-area the VK client reports (px). */
+export interface VKInsets {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+
+/**
+ * vkOnInsets subscribes to VK's safe-area insets and calls handler with them on launch and on change.
+ * VK reports them via VKWebAppUpdateConfig (iOS) and the dedicated VKWebAppUpdateInsets event; the VK
+ * mobile webview does not expose them through CSS env() the way iOS Safari does, so the app reads them
+ * from the bridge to clear the home bar (notably on Android). A no-op outside VK.
+ */
+export async function vkOnInsets(handler: (insets: VKInsets) => void): Promise<void> {
+  try {
+    const b = await bridge();
+    b.subscribe((e) => {
+      const d = (e as { detail?: { type?: string; data?: { insets?: Partial<VKInsets> } } }).detail;
+      if (d?.type !== 'VKWebAppUpdateConfig' && d?.type !== 'VKWebAppUpdateInsets') return;
+      const i = d.data?.insets;
+      if (!i) return;
+      handler({ top: i.top ?? 0, bottom: i.bottom ?? 0, left: i.left ?? 0, right: i.right ?? 0 });
+    });
+  } catch {
+    // Outside VK / bridge unavailable: the CSS env() safe-area fallback applies.
+  }
+}